This guideline focuses on best practices for writing technical documentation and on the style conventions to use when developing documentation for contributions. The goal of this guide is to help potential contributors and any one interested in contributing to documentation write material that is clear, concise, and consistent.
This guideline takes motivation from the following style manuals: If you are unable to find the answer to a style, voice, or terminology question in this guide, please consult these resources.
- Oxford Spelling, The Oxford Style Manual
- The Microsoft Manual of Style
- The Chicago Manual
- The Economist Style Guide
- Substrate Docs Writing Style Guide
- First Person: Do not use "I" or "me". Use the first person point of view sparingly and with intention. When overused, the first person narrative can overwhelm the sense of a shared experience and obscure the reader’s journey.
- Second Person: In most cases, address the reader directly. For tutorials, use either first person plural—we, us, our, ours—or second person point of view. Because tutorials provide a more guided approach to a topic, using the first person plural is a more natural and commonly-accepted practice than in other types of documentation.
- Third Person: Do not use “we” to refer to Polkadot.
- Active Voice: Use present tense whenever possible. There are situations where a passive voice is appropriate; revert to passive voice when the agent needs to be the focus.
- Keep the human presence in mind: having a dynamic tone when describing technical concepts really helps a reader connect with the material as opposed to describing software (or code) only for what it does.
- Pronouns: use gender-neutral pronouns, like “they” whenever possible. Generally, you can
change any noun from singular to plural to have subject-verb-pronoun agreement and avoid the
use of gender-specific pronouns like “he”, “him”, “his” or “she”, “her”, “hers”.
- Be wary of impersonal and potentially ambiguous pronouns. If you use any of the following
impersonal pronouns, be sure you answer “of what?”, “of which?”, or “as what?” in the sentence.
- all, another, any
- each, either
- few, many, neither, none,
- one, other
- same, several, some, such
- that, them, these, those
- Be wary of impersonal and potentially ambiguous pronouns. If you use any of the following
impersonal pronouns, be sure you answer “of what?”, “of which?”, or “as what?” in the sentence.
- Documentation is strong and meaningful when the necessary words and right phrases are used.
- Use common, well-known words whenever possible.
- Avoid flowery language and excessive literary phrases.
- Avoid jargon, colloquialisms, and idiomatic phrases.
- Avoid adverbs and subjective statements. For example, don’t use words and phrases that include easily, rapidly, simply, quickly. If need be, it is also better to underexaggerate than to overexaggerate.
- Don’t use phrases that introduce ambiguity. For example, instead of “When this release is live...” use “After this release is live...”.
- Pay extra attention to with word choice. Choosing to use “since” (implying a period of time) instead of “because” (implying cause and result) or using “once” (single occurrence) instead of “after” (each time).
- Avoid exclamation marks.
- Avoid adding unnecessary words or phrases. Some examples:
- Rather than saying “and then”, just use “then”.
- Rather than saying “In order to”, just use “to”.
- Rather than saying “as well as”, just use “and”.
- Rather than saying “via”, use an appropriate English substitute such as “using”, “through”, or “by”.
- Use a conversational tone that is not too formal, but should still be professional.
- Clarity: give life to the word or phrase where possible. For example:
- Rather than saying “e.g.”, use “for example”.
- Rather than saying “i.e.”, use “that is” or rewrite the sentence to make the meaning clear without needing extra qualification.
- Rather than saying “etc.”, use “and so on” or revise the content to make the term unnecessary. Instead of “etc.” to end a list of examples, focus on an example or two and use "such as" or "like".
- Instead of “caveat”, use an appropriate English substitute such as “notice”, “caution”, or “warning”.
- Contractions give documentation a more natural conversational tone—at least for English speakers. Be conscious of when and why you use contractions.