On-Prem User Guide Style Guide
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).
Using headings
Highlight text you want to apply the heading to
Select 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 (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').
Creating links to the Top of Page Anchor
Type 'Back to top' at the end of each section
Highlight the Back to top text
Select the Insert Link button (see image below)
Select Advanced from the menu on the left
Type #Top
Select 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).
Writing step-by-step instructions
Select 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 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.
Adding a tips, notes, or warnings macro
Select on the Plus Sign drop down (see image below)
Select 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
Select Insert
Type information within the tip, warning, or note space
Editing a tips, notes, or warnings macro
Select the icon beside the title of the tip, note, or warning
Select the Edit button
Select the Save button when done
Removing a tips, notes, or warnings macro
Select the icon beside the title of the tip, note, or warning
Select 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.
Inserting pictures
Select the Insert Files button (see image below)
Select the Upload Files button
Upload your .png or .jpg
Select the Insert button
Select the Border 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.
Sizing images in Confluence
Select the image
Do one of the following:
Adjust the pixel width in the text box to the left
Select 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
Select on the image
Select the Properties button
Select on Titles located on the left hand of the pop up/modal
Fill out Titles and Alt Text with a short description
Select the Save button
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).
Making your Table of Contents
Place your cursor next to your first Heading 1 title
Select the Plus Sign drop down (see image below)
Select the Other Macros option
Select 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
Select the Insert Link button (see image below)
Select Advanced from the menu on the left
Type # and the name of the anchor you made for that title (e.g. #Topic1)
Select Insert
Repeat steps 7-12 for the remainder of your 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.