Documentation Style Guide

Editorial guidelines for writing documentation

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.

Table of Contents

Language

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

General guidelines and best practices

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

Present tense

DoDon’t
CouchDB converts this to a properly hashed password when you save.CouchDB will convert this to a properly hashed password on save.

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

Active voice

DoDon’t
Stop everything and delete the medic DB to clear your database.Clear your db by stopping everything and deleting the medic DB.
Replicate your local production database into a new medic database to bootstrap your data.Bootstrap your data by replicating your local PROD DB into a new medic database.

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.”

DoDon’t
To create a database, …In order to create a database, …
See the configuration file.Please see the configuration file.
View the logs.With this next command, we’ll view the logs.

Address the reader as “you”

DoDon’t
You can create a database by …We’ll create a database by …
In the preceding output, you can see…In the preceding output, we can see …

Latin phrases

Prefer English terms over Latin abbreviations.

DoDon’t
For example, …e.g., …
That is, …i.e., …

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.

DoDon’t
Version 3.0 includes …In version 3.0, we have added …
Medic Mobile provides a new feature to reduce the time to load contacts.We made several changes to reduce the time to load contacts.
This page teaches you how to use medic-gateway.In this page, we are going to learn about medic-gateway.

Using jargon and idioms

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

DoDon’t
To get started, …To get up and running with no fuss, …
Internally, …Under the hood, …
Create a new database.Turn up a new database.

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.

DoDon’t
In version 3.4, …In the current version, …
The Log user statistics feature provides …The new Log user statistics feature provides …

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: >
     apps/guides/messaging/
     design/apps/
     ---
    

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.

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

DoDon’t
Read more about [InnoDB here](https://en.wikipedia.org/wiki/InnoDB).## [InnoDB here](https://en.wikipedia.org/wiki/InnoDB)
The [Icon Library]({{< relref "design/icons" >}}) has many great icons.## [Icon Library]({{< relref "design/icons" >}})

Formatting standards

Use Markdown Notation

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

StyleDoDon’t
italic_italic_ or *italic*<i>italic</i> or <em>bold</em>
bold**bold**<b>bold</b> or <strong>bold</strong>
table|...| using markdown tables<table><tr><td>...</td></tr></table>

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

DoDon’t
Click Fork.Click “Fork”.
Select Other.Select ‘Other’.

Italics to define or introduce new terms

DoDon’t
By default CouchDB runs in admin party mode, which means you do not need users to read or edit any data.By default CouchDB runs in “admin party” mode, which means you do not need users to read or edit any data.
The keys in .properties files are referred to as terms in POEditor.The “keys” in .properties files are referred to as terms in POEditor.

Code style for filenames, directories, and paths

DoDon’t
Open messages-en.properties file.Open messages-en.properties file.
The file is located in /config/standard directory.The file is located in /config/standard directory.
Create medic/translations/messages-en.properties file.Create medic/translations/messages-en.properties file.

British standard for punctuation inside quotes

DoDon’t
The doc in the database is a “record”.The doc in the database is a “record.”
The copy is called a “fork”.The copy is called a “fork.”

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.

DoDon’t
{{< figure src="image.png" class="right col-6 col-lg-3" >}}<img src="image.png" width="30%" align="right">
{{< figure src="image.png" class="right col-6 col-lg-3" >}}<img src="image.png" style="width:30%; align:right;">

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.

DoDon’t
{{< figure src="image.png" link="image.png" alt="Alt text" title="Image Title" >}}[![Alt text](image.png "Image Title")](image.png)

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 (`).

DoDon’t
The grunt dev-webapp command builds and deploys the webapp.The “grunt dev-webapp” command creates a Deployment.
To upload the configuration from your current directory, use medic-conf --local.To upload the configuration from your current directory, use “medic-conf –local”.
Enclose code samples with triple backticks. (```)Enclose code samples with any other syntax.

Code snippet formatting

Don’t include the command prompt

DoDon’t
export COUCH_NODE_NAME=couchdb@127.0.0.1$ export COUCH_NODE_NAME=couchdb@127.0.0.1

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.

TermUsage
DockerDocker should always be capitalized.
Community Health ToolkitCommunity Health Toolkit should always be capitalized.
CHTAcronym for “Community Health Toolkit”.
CouchDBNo space between Couch and DB. Do not use Couchdb, Couch DB or other variations.