User Documentation Style Guide

Owned by Johanna Carll
Last updated: Aug 23, 2022 by Margaret Kidd
5 min read

The following is a list of items to take into consideration while building out a Style Guide. Feel free to add notes or make comments on any of it.

For information on the Review Process, see the User Documentation Review Process page.

Layout and format - create a template

Basic standards for accessibility:

Font

  • Style-Sans serif

  • Font size -12 (minimum)

  • Font - black on a white page

  • Links - blue on a white page.

  • Bold text - bold text is sometimes used to highlight a term or to denote a button or field title. [Note: this has not been used consistently, the team should make a decision about using bold text]

Paragraph format

  • Line spacing

    • Around images - double space

    • Paragraph - single line space between paragraphs

  • Align left, no indent for paragraphs

  • Use underline for links only.

  • Do not use all caps.

  • Use only one space after a period.

Formatting headings

  • Page title - pre-defined by Confluence, when a page is created, it will automatically set the format, It uses the preset Heading 1.

  • Section titles - Manually formatted, Start with Heading 2, use Heading presets in sequential order for nested sections

Screenshots

  • Use this repository to create screenshots: ArchivesSpace User Docs test site

    • This is a test repository set up specifically for User Documentation. The purpose is to create standardized screenshots using real-world examples. These collections are from actual ArchivesSpace users so please be respectful of the data and don’t share it outside the scope of this team.

  • If you upload a new image that has the same title as an existing image, the new image will replace the existing image on the published page, even if you don’t publish your edits. To avoid this, append the date the screenshot was created to the file name (example: AccEdits_20210315)

  • Add alt text to images for accessibility.

    • If using the old editor, click on the image and select Properties to add alt text. If using the new editor, click on the image and select alt text.

    • If the image has a caption then alt text is not necessary.

    • Tips from Web Accessibility Evaluation Tool (WAVE):

      • “Alternative text should be succinct, yet descriptive of the content and function of an image. Lengthy alternative text (more than around 100 characters) often indicates that extraneous content or content that is not available to sighted users is being presented.”

      • “Ensure the alternative text is succinct, yet descriptive. Ensure that no content is being presented in the alternative text that is not available to sighted users viewing the image. When possible, either shorten the alternative text or provide the text alternative via another method (e.g., in text near the image, through a separate description page, etc.).”

      • Do not use quotation marks(“ “) or brackets [ ] in the alt text field as they are not supported in Confluence.

    • If using the alt text to communicate the full message in a screenshot then it is ok for it to be longer than 100 characters. ( Merge message, The resource [resource name] will have the select records merged into it. All select records will be deleted and any linked records will be re-linked to this resource.).

  • Where to place screenshots

    • Place the screenshot after the text describing it.

      • Immediately following the descriptive text? i.e. if we do step-by-step instructions would we want a screenshot for each step?

    • Use borderlines around the image to make it more visible. (Note, borderlines are not available in the new Confluence editor, there have been complaints so it may be added at a future date.)

      • If using the new editor, adding a caption can help delineate the image.

    • When making a screenshot, try to crop so that there is enough context for the user, but do not make it so large that it will be difficult to read.

Versioning a page

Pages should be versioned when edits are made to a page based on functional changes introduced in a new version.

  • Save the page to be versioned as a child of the current page. The child page will serve as instructions for users operating older versions of ArchivesSpace.

  • Append the title of the child page with the version number of the last relevant version. Use this format: (version x.x.x)

  • Add the following text under the title of the child page: Note: These instructions apply to an earlier release of ArchivesSpace. Please view the Table of Contents to access instructions for the current release. For information about the most current ArchivesSpace release, please visit: https://github.com/archivesspace/archivesspace/releases/latest

  • Append the title of the parent page with the first version the instructions refer to. Use this format: (from vx.x.x)

  • Make your edits to the parent page

  • For an example of a versioned page, see Import Archival Objects from Excel or CSV File (from v2.8.0)

Merging and deleting pages

There is no page merge function in Confluence, so merging is really copying and pasting across multiple pages and then deleting the unwanted pages. Deleting pages can only be done by the Community Engagement Coordinator.

  • Select a page to serve as the ongoing page

  • Copy and paste information from the pages that you want to merge into the ongoing page, then edit the page following the existing editing workflow

  • Once you publish the updated page, write to the Community Engagement Coordinator and ask them to delete the pages that are no longer needed. Provide links to the pages to avoid confusion over which ones to delete.

Linking to ArchivesSpace documentation outside of the Help Center

It’s better to link to information on the ArchivesSace website than to GitHub because Lyrasis/ArchivesSpace team has more control over the pages, but useful information can be found on both sites. Sources for additional information has been compiled on this page: https://archivesspace.org/application/technical-documentation

Content structure

Layout

Consider using Sections and page table of content macro (Possibly consolidate pages, improve navigation?)

  • Start each page with a narrative/explain the function.

  • If listing items or points, use bullet points.

  • If writing step-by-step instructions, use a numbered list.

  • End with use case scenarios? Should we have? If so, how many variations?

  • If highlighting an important point use an Info or Note panel to make it stand out. To see an example, view the User Defined Fields - Resources page.

Linking to glossary

  • What needs an entry in the glossary?

  • How to return from the glossary?

How to use abbreviations/acronyms

  • Try to avoid abbreviations if possible, unless if it is a very common one such as “e.g.” or “vs.”

  • For acronyms, if it is something the reader is likely to be unfamiliar with, write it out the first time with the acronym beside it in parentheses.

Use cases

Video tutorials

Done by another team. Let Jessica know if a video tutorial is needed.

  • Embedded on page or link to?

  • Should there be a video demo per page to illustrate the text?

Pagination and when to create a new page

  • Screenshot

  • Bullets are for lists

  • Numbering is for step-by-step instructions

Global application

  • Accessibility

  • Navigation