Active voice should be preferred over passive voice. Passive voice can be used, when it fits better.
**Example**
-**Active voice:** You want to render your own components in specific places in the Cart and Checkout.
-**Passive voice:** Slots and Fills add the possibility to render your own HTML in pre-defined places in the Cart and Checkout.
## Use the personal pronoun “you”
When using active voice, the second person singular (you) must be used.
## Don’t use gendered pronouns
Gendered pronouns (she/her/hers and he/him/his) must not be used.
## Filename must resemble the title
The filename of the document must match the title.
**Example**
-**Title:** Slots and Fills
-**Filename:** slots-and-fills.md
## Use correct heading hierarchy
Correct H1-H6 headings must be used. Each document can only have one H1 heading. An H3 heading can only be used within an H2 heading, an H4 heading can only be used within an H3 heading, etc. If possible, avoid using articles in headings.
**Example**
-**Incorrect:** The problem
-**Correct:** Problem
## Use semantically correct markup
The markup used must be semantically correct, e.g. list markup must only be used to display a list.
## Use correct spelling
Classes and tokens from the codebase must be written exactly as they appear in the codebase. Proper nouns must be written correctly.
**Example**
-**ExtendRestApi:** The `p` and the `i` of `ExtendRestApi` are written in lowercase
-**Composer:** The `C` of `Composer` is written in uppercase.
-**ESLint:** The `E`, the `S` and the `L` of `ESLint` are written in uppercase.
## Use images not wider than 50% width
Embedded images should not exceed a width of 50%.
## Use descriptive links
When linking to another document, a descriptive link text must be used.
**Example**
-**Incorrect:** Check this document
-**Correct:** Check the Slot Fill documentation
## Explain arguments
When listing or describing arguments, a table must be used to describe them. Refer to them as either arguments or props, depending on if they’re being used on a component or in a function/method. In the table, the description column should begin with a capital letter and end in a full stop. When listing an argument that is an array/object, list the argument name, type: array/object and a high-level description of what the purpose of the argument is. Then below, you detail the individual keys of the array/object.
**Example**
| Argument | Type | Default value | Required | Description |
import { registerExpressPaymentMethod } from '@woocommerce/blocks-registry';
```
</pre>
## Use table of contents for top-level readme
Every top-level README must have a table of contents. The table of contents can be generated automatically using the Visual Studio Code extension Markdown All in One.
## Use internal links
When listing features and options, e.g. ExperimentalOrderMeta, a table of contents with internal links must be used to allow jumping to the specific feature and option directly.
## Sort releases descending
Releases must be sorted starting with the most recent release.
**Example**
- 5.7.1
- 5.7.0
- 5.6.0
- 5.5.0
## Structure “How to” instructions
When explaining functionality, the following structure should be used:
- Problem
- Solution
- Usage
- Things to consider
- Putting it together
## Link references
When referencing other documentations, the corresponding document should be linked.
[We're hiring!](https://woocommerce.com/careers/) Come work with us!
🐞 Found a mistake, or have a suggestion? [Leave feedback about this document here.](https://github.com/woocommerce/woocommerce-gutenberg-products-block/issues/new?assignees=&labels=type%3A+documentation&template=--doc-feedback.md&title=Feedback%20on%20./docs/contributors/documentation-guidelines.md)
