Using this guide for writing and style
This guide focuses on best practices for writing technical documentation and on the style conventions to use when developing documentation for Parity Technologies products and audiences. The goal of this guide is to help members of the documentation team and any one interested in contributing to documentation write material that is clear, concise, and consistent.
This guide also includes peculiarities to working with this repo specifically for active contributors to be aware of available in the Builder notes section.
If you can't find the answer to a style, voice, or terminology question in this guide, consult the following resources:
General guidance for writing engaging content
There are three keys to writing content that engages the audience:
- Use the second person point of view to directly address the reader.
- Use an active voice and present tense whenever possible.
- Use a conversational tone that is not too formal or too chummy.
Point of view
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.
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.
Do not use “I” or “me” unless it appears in the text of a user interface element.
Do not use “we” to refer to Parity or the Substrate Developer Hub team. For example, if you are documenting a recommended setting or practice, use “Parity Technologies recommends....” not “We recommend...”.
Passive constructions
In spite of the axiom to never use the passive voice, there are situations where a passive sentence structure might be appropriate. Don’t twist a sentence into knots just to avoid a passive construction. Passive voice does have its place, but be wary of using it.
When writing about software, it’s often tempting to describe what’s happening from the code point of view. However, there’s almost always a human being with a goal or task to complete who is initiating the activity that the software is executing. If you keep this human presence in mind, your writing will be more dynamic, easier to follow, and more interesting to read.
Contractions and conversational tone
Contractions are generally acceptable because they give documentation a more natural conversational tone—at least for English speakers. Be conscious of when and why you use contractions.
To keep the tone conversational but concise, adhere to the following common-sense guidelines:
Use common, well-known words whenever possible.
Don’t use flowery language or literary flourish words and phrases like “and so forth”, “albeit”, “heretofore”, or “thus”.
Try to be precise in word choice. For example:
Don’t use “when”—implying eventuality and time—as interchangeable with “if”, which implies the possibility of something happening.
Don’t use phrases that introduce ambiguity. For example, instead of “When the process completes...” use “After the process completes...”.
Think carefully about word choices like using “since” (implying a period of time) instead of “because” (implying cause and result) or using “once” (single occurrence) instead of “after” (each time).
Avoid using dead language words and phrases even if they are generally accepted as English words in practice. For example:
Instead of “i.e.”, use “that is” or rewrite the sentence to make the meaning clear without needing extra qualification.
Instead of “e.g.”, use “for example”.
Instead of “via”, use an appropriate English substitute such as “by”, “through”, or “using”.
Instead of “etc.”, use “and so on” or revise the content to make the term unnecessary. For example, revise to use such as or like followed by an example or two.
Instead of “caveat”, use an appropriate English substitute such as “notice”, “caution”, or “warning”.
Avoid adding unnecessary words or phrases. For example:
Instead of “In order to”, just use “to”.
Instead of “as well as”, just use “and”.
Instead of “and then”, just use “then”.
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.
Experienced developers who truly prefer to skip the tutorial...
We can quickly test if this code is functioning as expected...
Headings
All heading levels should use the following conventions:
Use sentence style case.
Use active, present tense verbs in headings wherever appropriate, especially in the context of tutorials and how-to guides.
Serve as a summary of the content they contain.
Avoid generic headings like overview and introduction, if possible. While generic heading can be conceptually useful, they add no value to the content or the navigational experience.
Always contain content. A heading should never be immediately followed by another heading. As a best practice, avoid using headings strictly for navigation.
Limit heading levels
As a best practice, avoid building an information hierarchy with more than three heading levels. Most content can be effectively organized using two internal heading levels, making it easier to navigate and scan for relevant topics.
Topic titles
Avoid using gerunds (verbs that end with -ing) in titles and headings. Procedure titles and headings should answer the question: What are you trying to do? For example, if the answer to What are you trying to do? is I want to create an account, the article heading should be Create an account. In most cases, concept and reference topics are named with a noun phrase, such as Event hooks.
Lists
Introduce lists with a heading, a sentence, or a fragment that ends with a colon.
Use numbered lists for processes and procedures that must be completed in sequential order. Use bulleted lists for items that don't need to appear in order.
Make all list items parallel in structure. For example, start each item in the list using a noun or a phrase that starts with a verb.
Bullets
Bullets are for unordered lists. The order of items in a bulleted list can imply importance, but generally all list items are peers.
Each list item should start with a capital letter and end with a period unless all of the list items are single words or short phrases of no more than four words. Use parallel structure in phrasing the items in a list. For example, each list item might start with a verb, noun, or gerund.
Numbered steps
Only use numbered paragraphs for steps in procedures. If a procedure has more than nine steps, always consider breaking it into subsections with headings. Ideally, each procedure or subtask should be three to six steps, not have nested sub-steps, and have minimal embedded paragraphs describing what happens—the result or outcome to expect—in an unnumbered paragraph following the step.
Don't combine different actions into one step except when two actions complete a task, such as "Enter the user name, then click Next."
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 such as:
- all, another, any
- each, either
- few, many, neither, none,
- one, other
- same, several, some, such
- that, them, these, those
If you use any of these impersonal pronouns, be sure you answer “of what?”, “of which?”, or “as what?” in the sentence.
Terminology and usage conventions
This section covers common terminology, style, and usage questions and recommended practices.
Above and below
Don't use above to mean earlier or as an adjective preceding a noun (the above section) or following a noun (the code above). Use a hyperlink, or use previous, preceding, or earlier.
Don't use below to mean later or as an adjective preceding a noun (the below section) or following a noun (the code below). Use a hyperlink, or use later or the following.
For example: Use the preceding code to display information about the database. Use the following code to display information about the database.
Dates and numbers
Use the DD Mon YYYY or DD Month YYYY format for dates.
In body text, spell out whole numbers from zero through nine. Use numerals for 10 or greater. Use commas in numbers with four or more digits. Use more than instead of over (over is a spatial term).
Emphasis and admonitionments
Use bold formatting for user interface elements that the user interacts with, including:
- Dialog titles
- Field labels
- Buttons labels
- Options displayed in the user interface
Don't use bold, italics, or underlining for emphasis. If there's text that requires more attention than the surrounding body, consider isolating it as a standalone note or tip.
Use admonishment components sparingly! They are generally disruptive to the reader’s experience. Ask yourself if it is really necessary to stop the reader’s forward progress by adding a Note, Caution, or Tip component.
Note
Indicates neutral or positive information that emphasizes or supplements important points of the main text. A note supplies information that may apply only in special cases. Examples are memory limitations, equipment configurations, or details that apply to specific versions of a program.
Tip
Helps users apply the techniques and procedures described in the text to their specific needs. A tip suggests alternative methods that may not be obvious and helps users understand the benefits and capabilities of the product. A tip is not essential to the basic understanding of the text.
Caution
Advises users that failure to take or avoid a specific action could result in loss of data.
Images
Diagrams and illustrations can help readers visualize and internalize complex ideas and processes. So, use them liberally but with intention. Images also help to break up long text flows, but they should always reinforce and reflect the text immediately preceding or immediately following the image.
If you include screenshots, only include the relevant parts of the screen and use callouts to highlight how what is captured in the image is relevant to the text.
Be wary of using diagrams or illustrations that include any information—visual or textual—that is likely to get stale.
Log in formats
Most Linux distributions and macOS use log in to describe how a user initiates an interactive session. Windows uses log on.
Use log in as two words with no hyphen when describing an action (verb usage).
Use login as one word when used as a noun (rare but some platforms use login to mean user or an identity).
Use log-in with a hyphen when modifying a noun (adjective usage).
Optional steps
Use (Optional) to the beginning of steps that are optional. For example:
- Open a new terminal.
- Open the attributes file in a text editor.
- (Optional) Add a custom field.
Punctuation
| Element | How to use it |
|---|---|
| apostrophe (‘) | Use in contractions for a conversational tone. Avoid using the possessive form. |
| capitalization | Use sentence style capitalization for all headings. When referring to elements in the user interface, follow the capitalization that is used in the labels or text. Do not capitalize common terms. |
| colon (:) | Use a colon at the end of the statement that introduces a procedure, bulleted list, or table. |
| comma (,) | Use a serial comma to separate three or more items in a series, including the item before the conjunction. |
| em dash (—) | Use an em dash (—) to set off a parenthetical phrase with more emphasis than parentheses provide. Don’t add spaces around an em dash. Don’t capitalize the first word after an em dash unless the word is a proper noun. |
| hyphenation (-) | Avoid using hyphenated compound words. Use hyphens only if the meaning is unclear without them or if the only recognized form of the word includes a hyphen. |
| quotation marks (" ") | Avoid using quotation marks unless you need to quote a message or as tring that would otherwise be confusing given its surrounding context. |
| semicolons (;) | Don't use semicolons instead of commas to separate items in a list. If you think the content should use semicolons, consider rewriting it into subtopics or an unordered bullet list. |
| Slashes (/) and backslashes () | Avoid using slashes or backslashes except when documenting paths that require either forward or backward slashes. Never use and/or in documentation. |
Software versions
Use or later or and later to refer to multiple versions of software. For example:
- Firefox 3.6 or later
- Rust compiler (rustc) version 1.55.0 and later
Tense
Use present tense whenever possible. Use past tense only if you must describe something that has already occurred. Use future tense only if you must describe something that has not yet occurred but can be safely assumed.
User interface elements
In general, you should avoid writing about user interface elements. Instead, documentation should always focus on what the audience needs to do or wants to accomplish and not what is displayed on the screen.
| Element | What to do |
|---|---|
| button | Use bold for the button label. Don't include "button" in the description. For example: Click Submit. |
| checkbox | Use checkbox, not box or check box, if you need to refer to a checkbox in the user interface. Use select and clear with checkboxes, not turn on and turn off, mark and unmark, check and uncheck, or unselect and deselect. |
| click | Use click to describe taking action on a standalone button. Do not use click on. Click and select are not interchangeable. |
| dialog | If you need to refer to a dialog box, use dialog. Don't use pop-up window, dialog box, or dialogue box. |
| dropdown | Use dropdown as an adjective, not as a noun. For example, use dropdown list. |
Verb usage
| Verb | How to use it |
|---|---|
| allow, enable | Avoid using software as a point of view and consider rewriting to focus on the human interacting with the software. |
| can, may, might | Use the verb can when describing ability, capability, or capacity. Avoid using the verb may because it implies permission. Use the past tense might when describing the possibility or eventuality of an outcome. |
| clear | Use _clear rather than deselect or unselect if you have to describe removing a selection from a checkbox. |
| displays | Use the transitive verb displays rather than the intransitive verb appears. Use displays with a direct object. For example, The command displays log messages. |
| ensure | Use ensure to mean to make sure or to guarantee. Remember that this is not interchangeable with assure (to make confident) and insure (to provide insurance). |
| enter, type | Use enter to instruct the user to input a value by pressing the Enter or Return key. Use type to instruct the user to type a value in a field. |
| select | Use select to describe taking action on a menu item, checkbox, or radio button. Note that click and select are not interchangeable. |
| set up, setup | Use set up—two words, no hyphen—when used as a verb. Don't hyphenate. Use setup—one word, no hyphen—when used as an adjective or as a noun. |
| want, wish | Use want instead of wish or desire when the user has a choice of actions. |
Word choice
| Word in question | How to use it |
|---|---|
| affect, effect | Use affect as a verb and use effect as a noun. |
| app, application | Use application or applications unless there’s a specific reason for using the shorthand term app or apps. |
| back-end, front-end | Using the hyphen in these terms is still more common than not using it. Both forms are acceptable, but for consistency use the hyphen. |
| It hasn’t been e-mail for thirty-plus years. Never use emails. Don’t use email as a verb. | |
| file name | Use file name as two words, not filename. |
| its, it’s | Use its as a possessive meaning belonging to or associated with an object or idea previously mentioned. Because it is a vague pronoun, be sure what it refers to can be easily identified. Use it’s only as a contraction for it is or it has. |
| please | Avoid using please in documentation unless there’s a specific reason for using it. For example, you might use please if quoting the content of a message that asks the user to do something inconvenient. |
| prerequisite | As a section title, use Before you begin instead. If you use prerequisite in the text, there’s no hyphen. |
| that, which | Use that at the beginning of a clause that’s necessary for the sentence to make sense. Don’t put a comma before it. Don't use that when introducing a clause referring to people. Use who. Use which at the beginning of a clause that adds supporting or parenthetical information to a sentence. If you can omit the clause and the sentence still makes sense, use which, and put a comma before it. |
| user name | Use user name as two words, not username. |
Best practices and common mistakes
This section highlights best practices and common mistakes to avoid.
Make every word count
Concise sentences are easier to read, comprehend, and translate.
Use simple words with precise meanings.
Remove words that don’t add substance.
Avoid using passive to be verbs like been and being.
Avoid weak or vague verbs, such as have, make, and do.
When in doubt, choose the simple word or phrase over a more formal or complex one. For example:
| Use this | Not this |
|---|---|
| use | utilize, make use of |
| remove | extract, take away, eliminate |
| tell | inform, let know |
| to | in order to, as a means to |
| also | in addition |
| connect | establish connectivity |
Whenever possible, choose words that have one clear meaning. Omit unnecessary adverbs—words that describe how, when, or where. Unless they're important to the meaning of a statement, leave them out.
Be consistent
Use one term consistently to represent one concept. For example, if you use extrinsic, dispatchable, and transaction interchangeably or ambiguously, you’ll leave the reader confused and uncertain. If terminology changes, be prepared to root out old terminology.
If you use words that can be both nouns and verbs—for example, words like file, post, mark, screen, record, and report—use sentence structure and context to eliminate ambiguity.
Avoid dangling participles
Participles are modifiers so they must have a noun to modify. A dangling participle is a participle that doesn’t have a noun to modify. If you misplace or leave out the word being modified, you’ll end up with a sentence that is difficult to understand, illogical, or ambiguous (though potentially amusing). Here are a few examples of sentences with dangling participles:
Looking around the yard, dandelions sprouted in every corner.
Walking through the kitchen, the smoke alarm was going off.
Driving like a maniac, the deer was hit and killed.
You can correct these sentences by bringing the participle phrase closer to the subject the phrase is intended to modify or changing the word order of the sentence to clarify who is doing what. You can also fix these types of problems by changing the tense or using the active voice. For example:
Looking around the yard, I saw dandelions had sprouted in every corner.
As I was walking through the kitchen, the smoke alarm was going off.
Driving like a maniac, he hit a deer and killed it.
Dangling prepositions
In modern English, it’s perfectly acceptable to end a sentence with a preposition. Don’t twist a sentence into knots just to avoid using a preposition at the end.
This is something you might be interested in.
This is an example you should pay attention to.
Cross-reference formats
Most cross-references should include information that clarifies what the reader can expect to be found in the referenced topic.
For cross-references to topics in the Substrate documentation, use the following formats:
For more information about [task or concept], see [topic-title].
For cross-references in a glossary entry to other glossary entries, use the following format:
See [topic].
For cross-references to external resources, use the title of the destination instead of the URL of the destination.
Avoid using links to unnamed destinations. For example, don’t use links like click here or see this article.
Writing concept topics
Concept topics answer “why?” and “what is…?” questions. Use concept topics to:
Explain abstract ideas.
Introduce new terminology.
Offer analysis.
Provide background information.
The goal of a concept topic is to help the reader understand the bigger picture, the key components of a system or architecture, relationships between components.
Concept topics tend to be relatively stable, requiring little, if any, ongoing maintenance.
At a minimum, a concept topic includes at least one heading and one or more body paragraphs. A concept topic can also include:
One or more examples.
Two or more subsections, marked by subheadings.
A list of related topics.
Builder notes
This repository has some conventions and peculiarities that you need to take into account when
modifying it (in any way). Please read this entire section to avoid common gotchas and help make
your life and the maintainers lives easier.
New pages and moving files
- If you are adding or renaming a page, you must add it correctly in
src/components/DevNavMenu.tsxand possiblygatsby-config.jsandgatsby-node.js. Yourindex.mdxfile'stitleis not the source for the navigation rendering.
Internal link conventions
- All
/rustdoc/internal links must end with.htmlor.html#some-ID. Reasoning can be found in #425.
Check rendering images by clearing .cache
From time to time, the development server local cache becomes corrupted. To fix this in a one liner:
yarn clean && yarn dev
PLEASE do this when reviewing a page before every PR - this ensures your state is what the build CI see as well.
New or updated yarn packages
From time to time, BREAKING changes happen in the yarn dependencies. To fix this in a one liner
on main:
git checkout main && git pull && yarn install && yarn clean && yarn dev
Change the branch above to your working brach of choice, or start a new on for a new PR based on
latest main this way.
NOTE: please discard the "private": false, field this adds to package.json.