- Keep it short. Articles between 300-400 words are easy to read and support the user's workflow. Shorter articles are OK, but articles beyond 600 words are not. If necessary, organize the information into different articles.
- Each paragraph has a single purpose and describes a single concept. Avoid mixing concepts in the same paragraph or repeating the same information in different paragraphs.
- Use [admonitions](./style-conventions.md#admonitions) selectively and strategically. Documents with multiple admonitions are harder to read. Add the information as a regular sentence or paragraph if you use more than three admonitions in a single document.
A guide consists of two or more procedures in a single document.
## Concept: help me to understand
Concept articles describe a product's functionality. They complement procedures and provide non-procedural information.
For example, a user minting an NFT may not be interested in understanding the interactions with the Ethereum blockchain. For this user, a procedure explaining how to mint an NFT is sufficient. Others, however, may wish to understand this process in more detail, so a concept article on minting NFTs satisfies their curiosity.
Status documentation aims to guide users in completing tasks and exploring the different app features and functionalities. Therefore, concept topics are not as common as procedural topics.
A list of frequently asked questions (FAQs) falls under the concept category.
### Concept structure
| Element | # | Style | Required | Notes |
|:--|:--|:--|:--|:--|
| Title | 1 | H1 | **Yes** |
| Screenshot | 2 | PNG / GIF | No | The screenshot shows the area in the app related to the concept. |
| Admonition | 3 | Admonition | No | This admonition is exclusively to alert readers about the feature availability.</br>For example, a feature is only available to specific application role or available after completing another task. |
| Introduction | 4 | Paragraph | **Yes** | A brief discussion of the concept. |
| Example | 5 | Paragraph | No | An example explaining the concept in context. |
| **Correct** | Guide to Communities administration |
| Incorrect | Manage your Status Community |
| **Correct** | Understand your Status Community metrics |
| Incorrect | Understanding your Status Community metrics |
| **Correct** | About minting NFTs |
| Incorrect | Minting NFTs |
| **Correct** | FAQ: Import data from Discord |
| Incorrect | Importing data from Discord |
### Writing concepts
Use the [Concept structure](#concept-structure) and the [Style conventions](./style-conventions.md) in this style guide to write your concepts. Check out some of the topics on the [Status Help website :octicons-tab-external-16:][status-help]{:target="_blank"} to better understand how to create content.
## Procedure: help me to do
A procedure describes how to complete an action using a series of steps. Procedures help users use and discover the Status app and are the core of our user documentation. These are the main characteristics of procedures in Status user documentation:
- Two parts make up the procedure. The first part includes reference (non-procedural) information, while the second part includes procedural information.
- Non-procedural descriptions must be short and to the point. If the functionality requires further discussion, use an additional [concept article](#concept-help-me-to-understand).
- A procedure explains a single task and, if necessary, additional subtasks. If the task is complex, consider splitting it into different procedures or group them into a [guide](#guide-help-me-to-do-multiple-related-tasks).
- For tasks that may cause an error (for example, changing a password, choosing a user name, or sending crypto), consider adding a *Common questions* section at the end of the article, with answers to the most common issues. If the list of possible errors for a specific task is too long, use a [FAQ](#concept-help-me-to-understand) (concept) article instead.
- If the user can complete the procedure in one go, use a numbered list to describe the steps. Use checkboxes if the user can't complete the procedure in one go or the steps don't follow a particular order.
| Screenshot | 2 | PNG / GIF | No | The screenshot shows the area in the app where the discussion or action takes place.</br>Reference-only topics (tables) don't require this screenshot. |
| Admonition | 3 | Admonition | No | This admonition is exclusively to alert readers about the feature availability.</br>For example, a feature is only available to specific application roles or available after completing another task. |
| Introduction | 4 | Paragraph | **Yes** | A brief discussion of the functionality and its relationship with other functionalities.</br>The introduction answers the "what is this" |
| Example | 5 | Paragraph | No | An example explaining the functionality in context.</br>The example answers "why it matters." |
| **Correct** | Administer your Status Community tokens |
| Incorrect | Manage your Status Community tokens |
| **Correct** | Create an NFT for your Community |
| Incorrect | Make an NFT for your Community |
### **Writing tasks**
- If you introduce the task with a sentence (this is optional; see [Procedure structure](#procedure-structure)), don't repeat the title information. For example, if the task title is "Search for a contact using the Status display name," don't introduce the task with "To search for a contact using the Status display name [...]"
- In the first step, tell the user where to start.
- Follow the [UI elements guidelines](./style-conventions.md#ui-elements) to describe the user interactions.
For clarity purposes, the user interface elements in these examples don't follow the [UI guidelines](./style-conventions.md#ui-elements).
- Use words consistently when describing user actions. For example, if you use *remove* in one step, don't use *clear*, *empty* or another synonym in a different step.
- Don't describe to users what's happening on the screen, unless the result is unexpected.
- Limit the procedure to a maximum of six steps. If you need more steps to explain the task, create a subtask (see [Procedure structure](#procedure-structure)).
- Don't use sublists inside lists; instead, use a new list on a subtask.
- Use a period at the end of each step (check the [Punctuation](./style-conventions.md#punctuation) section for more information).
- When the action occurs in a specific menu or area in the user interface, write the location before the action.
- Don't use links in procedural steps, except when you need to reference a related subtask in the same article. You can use links in the optional paragraph before the steps.
- To describe menus or buttons in a particular user interface area, follow the order of the interface itself, going from left to right and from top to bottom. This means that if the user has the option to choose between *save* and *cancel* buttons, and the *save* button appears first, you should describe them in that order.
Reference articles support users as they perform a task. A reference article can be related to a procedure or work independently. Examples of reference topics are:
- A list of parameters
- A list of shortcuts
- Configuration settings
### Reference structure
Because of its nature, reference topics are mostly based on lists and tables.
| Element | # | Style | Required | Notes |
|:--|:--|:--|:--|:--|
| Title | 1 | H1 | **Yes** |
| Admonition | 2 | Admonition | No | This admonition is exclusively to alert readers about the feature availability.</br>For example, a setting is only available to specific application roles or available after completing a task. |
| Introduction | 3 | Paragraph | **Yes** | A brief discussion of the topic. |
| Admonition | 4 | Admonition | No | General notes, tips, or warnings about the topic. |
| Reference title | 5 | H2 | **Yes** |
| Explanation | 6 | Paragraph | **Yes** | One or more paragraphs describing the reference. |
| Reference table or list | 7 | Table / list | **Yes** | A table or bullet list with the relevant information.</br>This can also be included after the reference subtitle. |
| Reference admonition | 8 | Admonition | No | Notes, tips, or warnings about the reference. |
| Reference subtitle | 9 | H3 | No | When the main explanation requires a longer description, split the information into different subtitles. |
| Subtitle table or list | 10 | Table / list | No | A table or bullet list with the relevant information. |
| Subtitle admonition | 11 | Admonition | No | Notes, tips, or warnings about the reference. |
### Reference title
Use these guidelines for naming reference topics:
- Omit the verb in the sentence.
- Avoid meta-descriptions, like *list of [...]*, *table of [...]*, *a description of [...]*, and others.
