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.
Documentation for the Community Health Toolkit is written is American English.
This section contains suggested best practices for clear, concise, and consistent content.
Do | Don’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.
Do | Don’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.
Use simple and direct language. Avoid using unnecessary phrases, such as saying “please.”
Do | Don’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. |
Do | Don’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 … |
Prefer English terms over Latin abbreviations.
Do | Don’t |
---|---|
For example, … | e.g., … |
That is, … | i.e., … |
Exception: Use “etc.” for et cetera.
Using “we” in a sentence can be confusing, because the reader might not know whether they’re part of the “we” you’re describing.
Do | Don’t |
---|---|
Version 3.0 includes … | In version 3.0, we have added … |
Medic 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 cht-gateway. | In this page, we are going to learn about cht-gateway. |
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
Do | Don’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. |
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.
Avoid words like “currently” and “new.” A feature that is new today might not be considered new in a few months.
Do | Don’t |
---|---|
In version 3.4, … | In the current version, … |
The Log user statistics feature provides … | The new Log user statistics feature provides … |
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:
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!”
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.
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:
Do | Don’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" >}}) |
Documentation pages should be written in Markdown notation, and not contain HTML tags whenever possible.
Style | Do | Don’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> |
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:
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 |
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 %}}
{{% schedule %}}
and closing {{% /schedule %}}
shortcode must come before and after the markdown table respectively in order for it to correctly style the tableUse title case for page title
, and sentence case for linkTitle
description. Do not end titles with periods.
Use angle brackets for placeholders. Tell the reader what a placeholder represents.
<project_name>-medic-os-compose.yml
. Where <project_name>
is the name of one of your project.Do | Don’t |
---|---|
Click Fork. | Click “Fork”. |
Select Other. | Select ‘Other’. |
Do | Don’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. |
Do | Don’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. |
Do | Don’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.” |
Make notes and tips stand out by using blockquote styling.
{{% alert title="Note" %}} This is a sample note. {{% /alert %}}
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.
Do | Don’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.
Do | Don’t |
---|---|
{{< figure src="image.png" link="image.png" alt="Alt text" title="Image Title" >}} | [](image.png) |
Do | Don’t |
---|---|
right-hand side | right hand side |
left-hand | left hand |
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:
For inline code in an HTML document, use the ``` tag. In a Markdown document, use the backtick (`).
Do | Don’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 cht --local . | To upload the configuration from your current directory, use “cht –local”. |
Enclose code samples with triple backticks. (```) | Enclose code samples with any other syntax. |
Do | Don’t |
---|---|
export COUCH_NODE_NAME=couchdb@127.0.0.1 | $ export COUCH_NODE_NAME=couchdb@127.0.0.1 |
Verify the security settings on CouchDB:
curl http://localhost:5984
The output is similar to this:
{"error":"unauthorized","reason":"Authentication required."}
A list of terms and words to be used consistently across the site.
Term | Usage |
---|---|
Docker | Docker should always be capitalized. |
Community Health Toolkit | Community Health Toolkit should always be capitalized. |
CHT | Acronym for “Community Health Toolkit”. |
CouchDB | No space between Couch and DB. Do not use Couchdb, Couch DB or other variations. |
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.