Versions Compared

Old Version 6

changes.mady.by.user William

Saved on

compared with

New Version 7

changes.mady.by.user William

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Anchor
Top
Top
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. 

Each user guide should have an Overview section, a Table of Contents, and an Instructional Section. The setup should mirror this guide. If you are making net new documentation, we ask that you use the User Guide Template (Select the dots next to the Create button and choose USF IT User Documentation in the 'Select Space' drop down). 


Info
iconfalse
titleTable of Contents


Anchor
Topic1
Topic1
Structuring your user guide

Using headings

  1. Highlight text you want to apply the heading to
  2. Select the Paragraph drop down (see image below)
  3. Choose your heading (paragraph, Heading 1, Heading 3)

Info
titleHeading Best Practices
  • Paragraph/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 Insert Link button (see image below)
  4. Click Select Advanced from the menu on the left
  5. Type #Top
  6. Click Select Insert


Info
titleSection 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)

Back to top


Anchor
Topic2
Topic2
Formatting user guide instructions

Writing step-by-step instructions

  1. Click the Select the Numbered List button (see image below)
  2. Write instructions
  3. Bold and capitalize the Name of buttons and other options that the user is instructed to click/ select


Info
titleWriting 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 what should be selected 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 tips, notes, or warnings macro

  1. Click on Select on the Plus Sign drop down (see image below)
  2. Click the Select the Other Macros option
  3. Type tip, note, or warnings into the search bar
  4. Select the macro from the results
  5. Type the title of the tip, warning, or note
  6. Click InsertSelect Insert
  7. Type information within the tip, warning, or note space

Back to top

Editing a tips, notes, or warnings macro

  1. Click the Select the icon beside the title of the tip, note, or warning
  2. Click the Select the Edit button
  3. Slick the Select the Save button when done

Back to top

Removing a tips, notes, or warnings macro

  1. Click the Select the icon beside the title of the tip, note, or warning
  2. Click the Select the Remove button


Info
titleTips, 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


Back to top


Anchor
Topic3
Topic3
Using pictures in a user guide

Inserting pictures

  1. Click the Select the Insert Files button (see image below)
  2. Click the Select the Upload Files button
  3. Upload your .png or .jpg
  4. Click the Select the Insert buttonClick the 
  5. Select the Border button


Info
titleImage Treatments
  • Be consistent with how you draw attention to things in a picture. If you use red rectangles (recommended), use them throughout your pictures
  • Do not include more than 2 callouts in a picture. 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. Click the Select the image
  2. Do one of the following:
    1. Adjust the pixel width in the text box to the left
    2. Click on Select on one of the sizing buttons located between the text box and the original button


Info
titleImage 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


Back to top

Adding alt text to pictures

  1. Click on Select on the image
  2. Click the Select the Properties button
  3. Click onSelect on Titles located on the left hand of the pop up/modal
  4. Fill out Titles and Alt Text  with a short description
  5. Click the Select the Save button

Info
titleImages Best Practices
  • Draw attention to the button or clickable what should be selected by framing it with a red box (refer to the images in this Style Guide)

Back to top

Anchor
Topic4
Topic4
Finishing your user guide

Making your Table of Contents

  1. Place  your cursor next to your first Heading 1 title
  2. Click on Select the Plus Sign drop down (see image below)
  3. Click the Select the Other Macros option
  4. Click on Select on the Anchor macro
  5. Type the name of your anchor (i.e. Topic1)
  6. Repeat steps 1-5 for the remainder of your Heading 1 and Heading 3 titles
  7. Type your Heading 1 and Heading 3 titles in the Table of Contents space
  8. Highlight the first title
  9. Click the Select the Insert Link button (see image below)
  10. Click Advanced Select Advanced from the menu on the left
  11. Type # and the name of the anchor you made for that title (i.e. #Topic1)
  12. Click Select Insert
  13. Repeat steps 7-12 for the remainder of your titles


Info
titleAnchor 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


Back to top