Best practices
This section contains suggested best practices for clear, concise, and consistent content.
Use present tense
Yes |
No |
Cache-management operation instructions perform operations on copies of data in the memory hierarchy. |
Cache-management operation instructions will perform operations on copies of data in the memory hierarchy. |
Exception: Use future or past tense if it is required to convey the correct meaning.
Use active voice
Yes |
No |
You can use the RVWMO memory model |
The RVWMO memory model can be used |
The RVWMO memory model enables architects |
Architects are enabled by the RVWMO memory model. |
Exception: Use passive voice if active voice leads to an awkward construction.
Use simple and direct language
Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." Direct language is easier to translate.
Yes |
No |
To build a chip, |
In order to build a chip, |
See the Hypervisor extension. |
Please see the Hypervisor extension. |
View the register. |
With this next command, we’ll view the register. |
Address the reader as "you"
Using "we" in a sentence can be confusing, because the reader might not know whether they’re part of the "we" that you’re describing. Does it mean the RISC-V team, the RISC-V members, open source people, hardware people, or even everyone?
Yes |
No |
You can use the |
We’ll use the |
In the preceding output, you can see |
In the preceding output, we can see |
An exception to this rule is the rationale sections.
Avoid Latin phrases
Prefer English terms over Latin abbreviations. Latin terms can be difficult for translation because it adds an additional language to translate.
Yes |
No |
For example, |
e.g., |
That is, |
i.e., |
Avoid jargon and idioms
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
Yes |
No |
Internally, |
Under the hood, |
Stop trying. |
Chutar o pau-da-barraca (which translates to "kicking away the tent pole") |
Avoid statements about the future
Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.
An exception to this rule is documentation about announced deprecations targeting removal in future versions.
Avoid 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.
Do |
Don’t |
In version 1.4, |
In the current version, |
The pointer masking extension provides |
The new pointer masking extension provides |
Avoid words that assume a specific level of understanding
Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value and can actually make a user feel not up to the task.
Do |
Don’t |
Include one command in |
Include just one command in |
Run the command |
Simply run the command |
You can remove |
You can easily remove |
These steps |
These simple steps |
|
These guidelines were adapted from the Documentation style guidelines for Kubernetes in August of 2024. |