Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 9 Next »

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.

Step 1. Layout and format - create a template

Basic standards for accessibility

Font

  • style-Sans serif

  • Font size-12 (minimum)

  • Font has to be black on white page. Links should be blue on white page.

Paragraph format

  • Line spacing

    • Around images - double space

    • Paragraph - single

  • Align left, no indent for paragraphs

  • Use underline for links only.

  • Do not use all caps.

  • Use only one space after a period.

  • One line space between paragraphs to separate them since they are aligned left without indent.

  • Sections/Bullets/numbering

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

Formatting screenshots

  • 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, you should append the date the screenshot was created to the file name (example: AccEdits_20210315)

  • Add alt text to images for accessibility.

    • If using the older 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.

    • 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 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. (E.g. Ensure the alternative text is succinct, yet descriptive. Ensure that no content is being presented in 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.).

  • Where to place screenshots

    • Before or after a section?

    • 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 - Yes (Note, borderlines are not available in the new Confluence editor.)

    • How much to crop out (if you crop out too much, the image loses context.)

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 and save it 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 /wiki/spaces/ArchivesSpaceUserManual/pages/1173913646

Step 2. 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?

  • Followed by step by step instructions in list format?

  • bullets or numbering

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

  • Info boxes

Linking to glossary

  • What needs an entry in the glossary?

  • How to return from the glossary

How to use abbreviations.

Step 3. Format the style guide to mirror the style guide.

Step 4. Use cases

Video tutorials

Done by another team. Let Jessica know if 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

  • Screen shot

  • Bullets are for lists

  • Numbering is for step by step instructions

Step 5. Global application

  • Accessibility

  • Navigation

 

  • No labels