Overview
This style guide is an example of what customer-facing user guides should look like and how they should be structured. It includes best practices for user guides as well as instructions on how to navigate Confluence to add macros and a table of contents to your page that will function both in Confluence and Jira Service Desk Customer Portal.
Structuring your user guide
Using headings
- Highlight text you want to apply the heading to
- Click the Paragraph drop down (see image below)
- Choose your heading (paragraph, Heading 1, Heading 3)
Heading Best Practices
- Paragraph: Used for all instructional tasks and for tips, notes and warnings
- Heading 1: Used for major categories/headings in your user guide (i.e. 'Scheduling a meeting')
- Heading 3: Used for subcategories or subheadings in your user guide (i.e. 'Scheduling a one time meeting' or 'Scheduling a recurring meeting')
Creating links to the Top of Page Anchor
- Type 'Back to top' at the end of each section
- Highlight the Back to top text
- Click the Insert Link button (see image below)
- Click Advanced from the menu on the left
- Type #Top
- Click Insert
Section Best Practices
- Back to top should appear at the end of each section (Heading 1 and Heading 3) so users have easy access to the TOC.
- Check that your return to top links are working by using preview mode (see Final Check)
Formatting user guide instructions
Writing step-by-step instructions
- Click the Numbered List button (see image below)
- Write instructions
- Bold and capitalize the Name of buttons and other options that the user is instructed to click/select
Writing Instructions Best Practices
- Instructions throughout the user guide must start with a verb and be concise and succinct
- Draw attention to buttons or clickables by using directionals (i.e. upper left, lower right, etc.) or pictures
- Images should appear under the step that refers to the and "(see image below)" should be written in instructions
Adding a tips, notes, or warnings macro
- Click on the Plus Sign drop down (see image below)
- Click the Other Macros option
- Type tip, note, or warnings into the search bar
- Select the macro from the results
- Type the title of the tip, warning, or note
- Click Insert
- Type information within the tip, warning, or note space
Editing a tips, notes, or warnings macro
- Click the icon beside the title of the tip, note, or warning
- Click the Edit button
- Slick the Save button when done
Removing a tips, notes, or warnings macro
- Click the icon beside the title of the tip, note, or warning
- Click the Remove button
Tips, Notes, and Warnings Best Practices
- Tips: Use this macro for helpful troubleshooting tips
- Notes: Use this macro for reminders of important information that users often overlook
- Warnings: Use this macro to warn users of actions that can lead to poor results
Using pictures in a user guide
Inserting pictures
- Click the Insert Files button (see image below)
- Click the Upload Files button
- Upload your .png or .jpg
- Click the Insert button
- Click the Border button
Sizing images in Confluence
- Click the image
- Do one of the following:
- Adjust the pixel width in the text box to the left
- Click on one of the sizing buttons located between the text box and the original button
Image Sizing
- Size images so that they don't take up the whole page but users can also see what you are referring to without squinting
- Images should be sized no larger than 600px
Adding alt text to pictures
- Click on the image
- Click the Properties button
- Click on Titles located on the left hand of the pop up/modal
- Fill out Titles and Alt Text with a short description
- Click the Save button
Images Best Practices
- Draw attention to the button or clickable by framing it with a red box (refer to the images in this Style Guide)
Finishing your user guide
Making your Table of Contents
- Place your cursor next to your first Heading 1 title
- Click on the Plus Sign drop down (see image below)
- Click the Other Macros option
- Click on the Anchor macro
- Type the name of your anchor (i.e. Topic1)
- Repeat steps 1-5 for the remainder of your Heading 1 and Heading 3 titles
- Type your Heading 1 and Heading 3 titles in the Table of Contents space
- Highlight the first title
- Click the Insert Link button (see image below)
- Click Advanced from the menu on the left
- Type # and the name of the anchor you made for that title (i.e. #Topic1)
- Click Insert
- Repeat steps 7-12 for the remainder of your titles
Anchor Best Practices
- Anchor names should be short and unique from one another
- Anchor names must be typed the same way they appear on the anchor when creating links