Style & Tone¶
We aim to achieve a simple, easy-to-understand context for our technical and non-technical documentation. It aims to overlook the too-formal or robotic tone and give way to a friendly, inclusive and respectful tone of communication. It should call to action in a casual and approachable tone and should not sound pushy or dry.
As a contributor, if you are using an entertaining tone to help the readers better understand, do not go over the humour part. We generally assume that not every humour piece is universal and can be interpreted differently across different regions.
A few guidelines are employed to understand the style and tone. These are entirely flexible and are not universal for every context that we share amongst ourselves.
Approaches to be considered¶
Use Active voice wherever possible.
The style and tone should be friendly and come off as natural.
Making use of transaction words is quite preferred, to denote something related to a process or other action.
Simplify the documentation hierarchy for the readers to easily follow.
Technical terms, abbreviations, jargon should be documented early on in the document.
Brief, concise statements are preferred over wordy sentences.
Documentation pieces should be proofread by a peer or a fellow contributor.
Gender-neutral pronouns must be used for overall inclusivity.
Approaches to be not considered¶
Using gender-specific and culture-specific terminologies and figures of speech.
Using biased, unconfirmed or pre-assumed information pieces.
Using pretentious language to convince the reader of a fact or understanding. For example, This is the best way to do it, even though there is no supporting evidence to convince the reader about the same.
Using ableist language that is offensive to a group of people or community.
Being too polite; Avoid using words like “please” as it betrays the instructional nature of documentation.
Unnecessary capitalization, exclamation and use of abbreviations.
Apart from this, we heavily focus our documentation on two groups of people: users and developers. The users are researchers, scientists and government entities who use moja global projects to drive the decision-making process. The developers are community members who work on engineering, documentation, UI/UX designing and management to drive the projects at moja global forward.
We have some recommended practices involved while writing the documentation for these two groups:
For user-based documentation¶
While writing user-based documentation, we should consider that many of them may not be native English speakers. Hence using strong words, technical jargon, abbreviations may not be very suited for a documentation piece. The guidelines in this case are:
Maintain a clear and concise knowledge transfer from the documentation to the user.
Use short and crisp sentences that make easy sense to a user.
Use paragraphs to share a single context with the user. Avoid mixing multiple contexts in the same paragraph.
Consistent vocabulary and phrasing are of the utmost need here.
For developer-based documentation¶
While writing developer-based documentation, you can follow the same style as in the user-based documentation. You can assume the technical competency of the reader by putting prerequisites and a high-level overview of the technology you wish to cover. Some of the guidelines are:
Use instructive language to convey technical details and steps.
Avoid jumping the bandwagon while documenting technical steps.
Avoid using a conversational tone while documenting code and software references.
Use the second person while keeping the emphasis on the reader. For example, In this section, the user will run a module on their local machine to get the results is wrong. Prefer refactoring it into, In this section, you will run a module on your local machine to get the results.
Verify the documentation piece with a Subject Matter Expert (SME) before publishing.