This guide sets out a set of standards and guidelines for the formatting and layout of Knowledge Base content. It is intended to achieve:

• A consistent appearance for all content.
• Content that will be easy for users to read or scan.
  • Most online readers scan content for items of interest rather than read it from start to finish.
• Content that is easy for editors to create.
• Accessible content (for example, for screen-readers, and readers who can’t use a mouse).

Formatting and Layout

Text Styles

The Knowledge Base has a small set of defined text styles. You should not use anything other than these styles. (Do not change font face, size or colour).

• Heading 1 is reserved for the Content Title.
• Use Heading 2, Heading 3 etc. for section and sub-section headings.
  • Do not skip a level.
  • The Table of Contents will appear for items with more than three sections or sub-sections, and index Heading 2, Heading 3 and Heading 4.
  • Consistent use of Heading styles allows screen reader users to scan a page effectively.
• Use Title case for the all titles and headings:
  • This is an ‘Example of Title Case.’ All first letters are capitalised except an, the, of etc.
• Use Paragraph for the main body of the content.
• Do not use Preformatted text for code. Instead, use <> Code inline or {…} Code Insert for blocks of code.

Emphasis

• Use Bold very sparingly — if at all.
  • Too much Bold decreases readability, and stops text that really needs to be emphasised from standing out.
  • Other techniques should be used to highlight key points (and so improve the possibility for a user to scan a piece of content for what interests them).
    • Meaningful titles headings and sub-headings (not “clever” ones).
    • Bulleted or numbered lists.
    • Chunking.
• Use Capital Case for proper nouns:
  • This is an example of ‘Capital Case’. All first letters are capitalised.
• Key terms should not be highlighted. Terms in the Glossary will automatically be highlighted with a tool tip the first time they appear on a page. If a Glossary term appears in the content you’re editing, use Capital Case for the Term it wherever it appears.  Use Capital Case for other key terms sparingly — too much reduces readability.
• If you must use Bold (for example, for an important warning), WordPress will render it using the <strong> tag that screen readers can handle.
• Do not use Upper Case except to document keyboard sequences/shortcuts.
  • This is an example of ‘UPPER CASE’.
• Do not use Italics except to document ƒh interface elements.

Chunking

Chunking is breaking content up into small chunks, which makes it easier for users to process, understand and remember.  It helps avoid walls of text, which can appear intimidating or time-consuming. Chunking enables easy skimming — users’ preferred method of reading online.

Guidelines for effective chunking:

• Include a short summary paragraph at the start of long articles.
• Use short paragraphs, with white space to separate them (our WordPress theme adds the white space.)
• One idea per paragraph.
• Use short lines of text (around 50-75 characters).
• Use bulleted or numbered lists.
• Visually group related items together.
  • Keep related items close together and aligned.

User Directions

Large parts of the Knowledge Base will involve giving users directions to achieve an objective.

1. Use numbered lists or tables for step by step directions, in the order a user will go through the steps. (Be consistent about punctuation. If the step in a list is a sentence, place a full stop at the end.)
2. Use Italics for the names of windows, tabs, buttons or dialog boxes at the first mention only.
3. If you’re describing how to fill in fields on a screen, provide a screenshot and use a table with field name in the left hand column and value in the right hand column.
   • If using a table, ensure you set table and columns widths as %; this allows the table to resize gracefully.
4. Use <>Code for precise technical input such as Sentence Templates, Diagram Box Condition Expressions, Query Data References, File paths and name etc.
5. For brief pieces of user input (e.g. ‘names’, ‘addresses’, ‘places’, ‘notes’ etc.) where a table is not justified, use single quotes but ensure the context makes it clear that it is user input and that you are only providing an example.
6. Use the fH menu button option to highlight ƒh menu sequences   Do > this > Next
7. Use the ƒh icons option to show the icon a user should click. Format the icons according to the advice in How To Add Content to the Knowledge Base.
8. When entering keyboard key sequences/shortcuts, capitalise them. Keys that should be pressed simultaneously should be combined with a + sign: e.g. CTL+V .
9. Use “double quotation marks” to indicate screen prompts or error messages if the context does not make it clear.

Images and Videos

Images can make a page easier to read and understand. However, if your image is too big, too small, not aligned or grouped properly, or fades into the page, it will detract from the page’s information.

• Attempt to keep images no wider than 500 pixels in width.
  • Very small images (especially with text) are difficult to read and take up space without providing useful information.
  • If you need a wider image, consider making it the only thing on a row.
• Include space between text and an image to make sure the text is easier to read.
• Highlight areas on a screenshot with a simple red box if that will make it easier for the reader to understand.
• If your image includes text directions, you must spell those directions out on the page. Screen readers cannot read the text on an image.
• Include a caption if it is useful to understand the purpose or detail of the image and/or to acknowledge the source of the image and make any associated copyright statement.
  • It is not necessary to acknowledge Calico Pie for screenshots taken from Family Historian.
  • If no caption is necessary, ensure the image in the media library has alt-text associated with it for the benefit of people using screen readers.

Images and videos can aid comprehension for people with particular learning styles, but should not be a substitute for text instructions.

Links

• When adding a link, include meaningful text to describe what you’re linking to, and check that it works.
  • ‘Here’ or ‘this’ is not meaningful text.
  • For links to other pages within the Knowledge Base, the text must be the name of the destination page.
• Check that any link you’ve added works.

Terminology

Grammar and spelling

Accurate grammar and spelling are important. Make proof read content before publishing. Most major browsers have a built-in spell checker. Use that to verify correct spelling.