Documentation Style Guide

This style guide provides a set of editorial guidelines for anyone writing documentation for Community Health Toolkit projects. These are guidelines, not rules. Use your best judgment.

Language

Documentation for the Community Health Toolkit is written is American English.

Voice and tone

The voice and tone should be inclusive and accessible to its audience. Consider that readers come from different backgrounds and may have varying levels of ability reading English, as well as technical abilities.

Write like you speak

Aim for a voice and tone that’s conversational and approachable. Try to sound like a knowledgeable friend who understands what the developer wants to do.

Get to the point quickly

Lead with what’s most important. Make steps obvious to make your documentation easily scannable.

Be brief

Give the audience just enough context and information to make decisions confidently. Avoid long sentences.

General guidelines and best practices

This section contains suggested best practices for clear, concise, and consistent content.

Present tense

Exception: Use future or past tense if it is required to convey the correct meaning.

Active voice

Exception: Use passive voice if active voice leads to an awkward construction.

Simple and direct language

Use simple and direct language. Avoid using unnecessary phrases, such as saying “please.”

Address the reader as “you”

Latin phrases

Prefer English terms over Latin abbreviations.

Exception: Use “etc.” for et cetera.

Practices to avoid

Using “we”

Using “we” in a sentence can be confusing, because the reader might not know whether they’re part of the “we” you’re describing.

Using jargon and idioms

Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.

Using statements about the future

Avoid giving hints about the future. If you need to talk about an alpha or beta feature, put the text under a heading that identifies it as alpha or beta information.

Using statements that will soon be out of date

Avoid words like “currently” and “new.” A feature that is new today might not be considered new in a few months.

Cross-referencing content

Connecting readers to related content in different pages is an important aspect of documentation. There are three ways this can be done in the doc site:

1. Inline links: a portion of any narrative text can link to another page. This should done using the markdown link notation.

   For example, the text linking documents is a [foundational reason for the web existing in the first place](https://en.wikipedia.org/wiki/Hypertext)! yields: “linking documents is a foundational reason for the web existing in the first place!”

2. See Also: the see-also shortcode is available to connect to an important concept within the documentation site. The link will be more prominent to the reader by having a common prefix and shown on a separate line.

   For example, {{< see-also page="design/icons" >}} will show as seen here:

   See Also: Icon Library

   You can also make the callout say “Read More” with the prefix tag: {{< see-also prefix="Read More" page="design/icons" >}}. This will show as seen here:

   Read More: Icon Library

   A custom title and anchor can be provided as well. For example, {{< see-also page="design/icons" title="Learn about the Icon Library" anchor="about-the-icon-library" >}}, will show as:

   See Also: Learn about the Icon Library

   Please use see-also when referencing related topics , as seen in Workflows, and use read-more when referencing the same topic in more depth, as in the Home Page.

3. Related Content: Pages within the documentation site are often closely related, but are separated by the type of content. For instance, a topic may be described in the features, have an implementation guide, and have best practices in the design system. To make this linkage easier for documentation writers and readers, a “Related Content” section can be shown at the bottom of the page. Each page defines it’s own related content as relatedContent in its front matter. For example, a page with the following front matter would have two pages shown as Related Content.

   ---
   title: Messaging
   relatedContent: >
    building/guides/messaging/
    design/building/
    ---
   

Avoid broken links

To avoid broken links always use ref or relref shortcodes for internal references with the full path for the page. Check out the Hugo documentation for cross-references for more details.

For example, [Icon Library]({{< relref "design/icons" >}}) yields “Icon Library”. Using the full path will avoid ambiguous references if a new page of the same is created.

Link paragraphs, not titles

Whether using ref ,relref or inline links, do not link a title:

Formatting standards

Use Markdown Notation

Documentation pages should be written in Markdown notation, and not contain HTML tags whenever possible.

Tabular schedules

Displaying the occurrence of events over time in a workflow is often done using a table. To keep these consistent we recommend using the tabular schedule format.

For example, here is a sample vaccination schedules:

To achieve this use a markdown table with the letter X (X) to mark events, leaving cells empty when no action is needed. The shortcode {{% schedule %}} is used before and after the markdown table so that built-in styling can be applied. Here is the code for the above example:

{{% schedule %}}
|| 6m | 12m | 18m | 2y | 2.5y | 3y | 3.5y | 4y | 4.5y | 5y |
|------------|--|--|--|--|--|--|--|--|--|--|
| Deworming  | |   | X | X | X | X |  | X | X | X |
| Vitamin A  | X | X | X | X | X | X | X | X | X | X |
{{% /schedule %}}

Grammar and punctuation in headers

Use title case for page title, and sentence case for linkTitle description. Do not end titles with periods.

Angle brackets for placeholders

Use angle brackets for placeholders. Tell the reader what a placeholder represents.

1. Create a file named <project_name>-medic-os-compose.yml. Where <project_name> is the name of one of your project.

Bold for user interface elements

Italics to define or introduce new terms

Code style for filenames, directories, and paths

British standard for punctuation inside quotes

Number formatting

Avoid the use of comma or period as thousands separator since it can be confused for a decimal point in some countries. Either use no separator for small numbers or a unicode Thin Space which is often recommended for international documents.

There’s a shortcode format-number which will replace _ with Thin Space to simplify formatting in this way.

Notes and tips

Make notes and tips stand out by using blockquote styling.

{{% alert title="Note" %}} This is a sample note. {{% /alert %}}

Images

The image markdown syntax can be used for images, but if any styling is required use the built-in figure shortcode. With the figure shortcode many fields are configurable, and the position and size can be responsive with Bootstrap grid classes. You should avoid using the HTML img tag in the documentation.

It is good practice for the image to link to the image file so that a larger version can be viewed easily. This can be done using the link attribute with the figure shortcode, which is less error prone than adding a link to the markdown image notation.

Indicating location of items on the screen

Where to place your images

To ensure your images are loaded on the docsite in the right format,place them in a folder that is named similar to your .md file. For example in the scenario below, the image is linked in the style-guide.md file, thus it is placed in the style-guide folder.

Videos

When embedding videos, use the youtube shortcode to embed a responsive YouTube video player.

Copy the YouTube video ID that follows v= in the video’s URL and pass it to the youtube shortcode. For instance, with https://www.youtube.com/watch?v=pFEFIY_SA7M the shortcode would be:

{{< youtube pFEFIY_SA7M >}}

And would display as seen here:

Inline code formatting

Code style for inline code and commands

For inline code in an HTML document, use the ``` tag. In a Markdown document, use the backtick (`).

Code snippet formatting

Don’t include the command prompt

Separate commands from output

Verify the security settings on CouchDB:

curl http://localhost:5984

The output is similar to this:

{"error":"unauthorized","reason":"Authentication required."}

Community Health Toolkit word list

A list of terms and words to be used consistently across the site.