Cloud User Guide Style Guide

Owned by William
Last updated: Aug 19, 2021

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 (Cloud and On-Prem) to add macros and a table of contents to your page that will function both in Confluence and Jira Service Desk Customer Portal. 

Each user guide should have an Overview section, a Table of Contents (TOC), and an Instructional Section. The setup should mirror this guide.  

Table of Contents

Structuring your user guide

Using headings

  1. Highlight text you want to apply the heading to
  2. Select the Normal text drop down
  3. Choose your heading (Normal text, Heading 1, Heading 3)

Heading Best Practices

  • Normal text: Used for all instructional tasks and for tips, notes, and warnings.
  • Heading 1: Used for major categories/headings in your user guide (e.g. 'Scheduling a meeting').
  • Heading 3: Used for subcategories or subheadings in your user guide (e.g. 'Scheduling a one-time meeting' or 'Scheduling a recurring meeting').

Back to top

Creating links to the Top of Page Anchor

  1. Type 'Back to top' at the end of each section
  2. Highlight the 'Back to top' text
  3. Select the Link icon
  4. Type #Top and then press Enter


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 Finishing your user guide).

Back to top


Formatting user guide instructions

Writing step-by-step instructions

  1. Select the Numbered list icon
  2. Write instructions
  3. Bold and capitalize the Name of buttons and other options that the user is instructed to select


Writing Instructions Best Practices

  • Instructions throughout the user guide must start with a verb and be concise and succinct.
  • Draw attention to all items that are selectable (buttons, icons, etc.) 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.


Back to top

Adding a panel

  1. Select the Insert (Plus sign) drop down
  2. Type 'panel' into the search bar
  3. Select the wanted panel from the results
  4. Type in bold the title of the panel if desired
  5. Type the information within the panel

Back to top

Editing a panel

  1. Select the panel to be adjusted
  2. Edit the wanted text
  3. Select anywhere outside of the panel once editing is complete to exit the editor

Back to top

Removing a panel

  1. Select the panel
  2. Select the Remove (Trash can) icon


Tips, Notes, and Warnings Best Practices

  • Info: Use this panel for general or generic information pertaining to the topic.
  • Note: Use this panel for reminders of important information that users often overlook.
  • Success: Use this panel for helpful troubleshooting tips.
  • Warning: Use this panel to warn users of actions that can lead to poor results.
  • Error: Use this panel to warn users of actions that can lead to serious breaks/complications/issues/problems. Things that can disrupt the process for the user.


Back to top


Using pictures in a user guide

Inserting pictures

  1. Place the cursor where the file or image is wanted 
  2. Select the Files & Images icon
  3. Navigate to the location of the wanted file or image
  4. Select the wanted file or image
  5. Select the Open button

Image Treatments

  • Be consistent with how you draw attention to things in an image. If you use red rectangles (recommended), use them throughout your images.
  • Do not include more than 2 callouts for an image. This can cause confusion with your end-user, and they won't know which action to perform first.


Back to top

Sizing images in Confluence

  1. Select the image 
  2. Drag the handles on either side of the image to decrease or increase the image size.

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.
  • Use the guidelines that appear when the image is selected to align all images when resizing.


Back to top

Adding alt text to pictures

  1. Select the image
  2. Select the Alt text text in the floating menu by the image
  3. Enter a short description of the image
  4. Press Enter or select anywhere outside of the image to save the entered information

Images Best Practices

  • Draw attention to the items that are selectable (buttons, icons, etc.) by framing it with a red box (refer to the images in this Style Guide).

Back to top


Finishing your user guide

Making your Table of Contents

  1. Add Info panel
  2. Place  your cursor next to your first Heading 1 title on the right
  3. Select the Insert (Plus Sign) icon drop down
  4. Type 'anchor' in the search bar
  5. Select Anchor under the search bar
  6. Type the name of your anchor (e.g. Topic1) in the pop-out on the right side of the screen in the Anchor Name field. 
  7. Repeat steps 2-6 for the remainder of your Heading 1 and Heading 3 titles
  8. Type your Heading 1 and Heading 3 titles in the Table of Contents space 
  9. Highlight the first title
  10. Select the Link icon
  11. Type # and the name of the anchor you made for that title (e.g. #Topic1) and then press Enter
  12. Repeat steps 8-11 for the other titles


Anchor Best Practices

  • Anchor names should be short, have no spaces, and be unique from one another (e.g. #Topic1, #Topic2, etc.).
  • Anchor names must be typed the same way they appear on the anchor when creating links.

Back to top