status-im
/
write.status.im
mirror of https://github.com/status-im/write.status.im.git
2
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

43 Writing style guide updates -- July 2023

This commit is contained in:
Jorge Campo 2023-07-11 11:50:51 +02:00
parent 3fd9b327a0
commit d263741a7b
No known key found for this signature in database
GPG Key ID: 5FD1E8DD19600AC4
4 changed files with 112 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
docs/index.md
View File

@ -1,6 +1,6 @@
---
id: 12
revision: 2
revision: 3
hide:
- navigation
---
@ -14,7 +14,7 @@ The Status writing style guide aims to provide easy-to-follow guidelines for wri
This guide doesn't contain lengthy linguistic explanations. Instead, it's intended to be a simple, real-world resource for anyone willing to contribute to the Status documentation, from writers ready to document product functionalities to casual contributors who want to improve the existing content.
The [Style guidelines](style-guidelines.md) section describes Status general approach to technical writing style and content structure. In [Structuring the content]](./structuring-the-content.md), you can find the different types of articles in the Status documentation, including directions on structuring your content. The [Style conventions](./style-conventions.md) section serves as a reference to the different styles in the Status documentation. Finally, [Terminology](./terminology.md), provides a list of common Status product names, as well as icon names and user interface areas names in the Status apps.
The [Style guidelines](style-guidelines.md) section describes Status general approach to technical writing style and content structure. In [Structuring the content](./structuring-the-content.md), you can find the different types of articles in the Status documentation, including directions on structuring your content. The [Style conventions](./style-conventions.md) section serves as a reference to the different styles in the Status documentation. Finally, [Terminology](./terminology.md), provides a list of common Status product names, as well as icon names and user interface areas names in the Status apps.
Refer to our [documentation contributor's guide][contributors-guide] to contribute to this guide or the Status documentation.
@ -23,10 +23,10 @@ Refer to our [documentation contributor's guide][contributors-guide] to contribu
<div class="grid cards" markdown>
- [:triangular_ruler: Style guidelines][style-guidelines]
- [:construction_site: Structuring the content][structuring-the-content]
- [:paintbrush: Style conventions][style-conventions]
- [:abcd: Terminology][terminology]
- [Style guidelines][style-guidelines]
- [Structuring the content][structuring-the-content]
- [Style conventions][style-conventions]
- [Terminology][terminology]
<br>

23
docs/structuring-the-content.md
View File

@ -1,6 +1,6 @@
---
id: 12
revision: 6
revision: 8
hide:
- navigation
---
@ -13,8 +13,11 @@ This document provides guidelines to create easy-to-read and follow topics for t
- 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.
- When there is more than one way to do something or describe something, use the most straightforward way only. Don't discuss all the possible ways.
- Use [admonitions](./style-conventions.md#admonitions-callouts) 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.
!!! tip
If it's worth mentioning an alternative method of completing a procedure, use a tip-style admonition to describe the alternative way briefly.
## Types of documents
@ -54,8 +57,8 @@ Status documentation aims to guide users in completing tasks and exploring the d
| 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. |
| "The basics" title | 6 | H2 | **No** | H2 title reads "The basics." |
| "The basics" list | 7 | Unordered list | **No** | A list summarizing the article's main takeaways. |
| "The basics" title | 6 | H2 | No | H2 title reads "The basics." |
| "The basics" list | 7 | Unordered list | No | A list summarizing the article's main takeaways. |
| Admonition | 8 | Admonition | No | General info, tips, or warnings about the topic. |
| Explanation title | 9 | H2 | **Yes** |
| Explanation | 10 | Paragraph | **Yes** | One or more paragraphs describing the concept in detail. |
@ -93,6 +96,7 @@ A procedure describes how to complete an action using a series of steps. Procedu
- 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.
### Procedure structure
@ -100,13 +104,13 @@ A procedure describes how to complete an action using a series of steps. Procedu
![Layout of the procedure type topic](./structuring-the-content/12-4-4-dark.png#only-dark)
| Element | # | Style | Required | Notes |
| --- | --- | --- | --- | --- |
|:---|:---|:---|:---|:---|
| Title | 1 | H1 | **Yes** |
| 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." |
| "What to expect" title | 6 | H3 | No | H3 title reads "What to expect." |
| "What to expect" title | 6 | H2 | No | H2 title reads "What to expect." |
| "What to expect" list | 7 | Unordered list | No | List the expected results after completing the task. |
| Admonition | 8 | Admonition | No | General notes, tips, or warnings about the task. |
| Tasks title | 9 | H2 | **Yes** |
@ -119,8 +123,8 @@ A procedure describes how to complete an action using a series of steps. Procedu
| Subtask screenshot | 16 | PNG / GIF | No |
| Subtask admonition | 17 | Admonition | No | Info, tips, or warnings about the task. |
| Common questions title | 18 | H2 | No | H2 title reads "Common questions". |
| Common question subtitle | 19 | H3 | No | Common question subtitle. |
| Common question paragraph | 20 | Paragraph | No | Answer to the common question. |
| Common questions subtitle | 19 | H3 | No | Common questions subtitle. |
| Common questions paragraph | 20 | Paragraph | No | Answers to common questions. |
(*) Subtasks don't include an introduction sentence.
@ -206,7 +210,8 @@ A procedure describes how to complete an action using a series of steps. Procedu
| **Correct** | To remove the user from your contact list, tap Block user. |
| Incorrect | Tap Block user to remove the user from your contact list. |
- Don't use links in procedural stpes, except when you need to reference a related subtask in the same article. You can use links in the optional paragraph before the steps.
- 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: help me to remember

111
docs/style-conventions.md
View File

@ -1,6 +1,6 @@
---
id: 12
revision: 10
revision: 11
hide:
- navigation
---
@ -74,11 +74,13 @@ We prioritize simplicity over comprehensiveness. If you can't find a particular
- Use the article's title in all-lowercase letters for the Markdown file name.
- Use a dash symbol ("-") to replace spaces.
- Don't exclude articles, prepositions, or any other word in the Markdown file name.
- If the name includes apostrophes, remove them from the Markdown file name.
- If the name includes apostrophes, remove them from the Markdown file name. If the apostrophe is part of the [possesive form](#possessive-form) with an extra *s* letter, separate the letter in the name (example: `transfer-you-community-s-ownership`).
| Usage | Article name | Markdown file name |
|:------------|:----------------------------------------|:---------------------------------------------|
| **Correct** | Browse people and Communities in Status | `browse-people-and-communities-in-status.md` |
| **Correct** | Transfer your community's ownership | `transfer-your-community-s-ownership` |
| Incorrect | Trasnfer your community's ownership | `transfer-your-communitys-ownership` |
| Incorrect | Browse people and Communities in Status | `Browse-people-and-Communities-in-Status.md` |
| Incorrect | Browse people and Communities in Status | `browse-people-communities-status.md` |
| **Correct** | FAQ: Import data from Discord | `faq-import-data-from-discord.md` |
@ -138,10 +140,12 @@ We prioritize simplicity over comprehensiveness. If you can't find a particular
- Use a comma before *such as*.
- Use a comma after *for example*.
- Use the Oxford comma for *and* and *or* conjunctions where the meaning of your sentence would otherwise be unclear. In other cases, avoid placing the extra comma.
- In procedural steps, don't write a comma in sentences such as *click on cancel, and then...*
- Use these guidelines for periods:
- Use a period at the end of a sentence, including sentences ending on a [URL](#links).
- Observe the punctuation rules for items on a [bullet list](#bullet-lists).
- Don't use semicolons. Instead, use a period and write the text after the semicolon in a new sentence.
- Avoid preceding tables with colons. Instead, use a period.
- Don't use dashes (_em_ or _en_ dashes.) Instead, use parenthesis if you need to clarify information.
- Use parenthesis sparingly, and don't write essential information inside parenthesis.
- Don't use bold or italics with punctuation symbols.
@ -217,6 +221,9 @@ You can also use tables to compare the available options across different elemen
Remember that users may access the information using a smartphone. Therefore, if your table contains a lot of information or more than three or four columns, consider organizing it differently or using more than one table.
!!! tip
You can use [links](#links) in tables except if the table is part of a procedure step.
## Numbers, date and time, currencies, and units of measure
- In body text, spell out whole numbers from zero through nine and use numerals for 10 or greater.
@ -229,16 +236,23 @@ Remember that users may access the information using a smartphone. Therefore, if
| Incorrect | 0,13 |
| Incorrect | 0'13 |
- Don't use the thousand separator. While the separator improves readability (especially for very long numbers), their symbol and placement vary among countries.
- When writing in English, use a comma (,) as the thousand separator and a colon (.) as the decimal separator to improve readability. For languages other than English, use the commonly accepted rule in the country or a comma if a common practice is unknown or controversial.
| Usage | Example |
|:------------|:--------|
| **Correct** | 2500 |
| Incorrect | 2,500 |
| **Correct** | 12500 |
| Incorrect | 12.500 |
| **Correct** | 118000 |
| Incorrect | 118'000 |
!!! note
There isn't a common notation for thousand and decimal separators and notation varies among different countries. In the United States, the decimal separator is a period (.) and the thousands separator is a comma (,). In Germany, the decimal separator is a comma (,) and the thousands separator is a period (.). In Sweden, the thousands separator is a space.
| Usage | Example |
|:------------|:------------|
| **Correct** | 2,500 |
| Incorrect | 2500 |
| **Correct** | 12,500 |
| Incorrect | 12.500 |
| **Correct** | 2,500.46 |
| Incorrect | 2.500,46 |
| **Correct** | 118,000 |
| Incorrect | 118 000 |
| **Correct** | 118,000,000 |
| Incorrect | 118'000'000 |
- Don't use *rd.* or *th.* to express dates or indicate the order of things.
@ -268,7 +282,6 @@ Remember that users may access the information using a smartphone. Therefore, if
| Incorrect | half past eight |
- Use the [UTC time standard :octicons-tab-external-16:](https://en.wikipedia.org/wiki/Coordinated_Universal_Time){:target="_blank"} when writing for a global audience.
- For cryptocurrencies, NFTs, or DeFi tokens, use the symbol described on their website or use the symbol from [CoinMarketCap :octicons-tab-external-16:][coinmarketcap]{:target="_blank"} or [CoinGecko :octicons-tab-external-16:][coingecko]{:target="_blank"} websites.
- To write a crypto amount, place the symbol after the number.
- To write fiat, use the [ISO4217 :octicons-tab-external-16:][ISO4217] currency symbol after the amount. If you're using fiat to illustrate a concept, use [commonly-known currencies :octicons-tab-external-16:][wikipedia-common-currencies] like the USA dollar (USD), Euro (EUR), or Japanese yen (JPY).
@ -286,9 +299,18 @@ Use links to other articles in the Status documentation, but don't abuse links.
| Usage | Example |
|:--------------|:------------------------------------------------------------------------|
| **Correct** | To learn more about tokens, check the *Understad Status tokens* article |
| **Incorrect** | To learn more about tokens, check *this* article |
| **Correct** | For more details about tokens, check the *Understad Status tokens* article |
| **Incorrect** | For more detals about tokens, check *this* article |
- When pointing the user to external sources, start you sentence with *For more details*.
| Usage | Example |
|:--------------|:---------------------------------------------------------------------------|
| **Correct** | For more details about tokens, check the *Understad Status tokens* article |
| **Correct** | For more details, check the *Understad Status tokens* article |
| **Incorrect** | To learn more about tokens, check *this* article |
| **Incorrect** | For more information about tokens, check *this* article |
- For links outside of the Status documentation site, use the `:octicons-tab-external-16:` icon (part of the [Material for MkDocs icons bundle :octicons-tab-external-16:][material-mkdocs-icons]) at the end of the link description.
| Usage | Example |
@ -369,13 +391,13 @@ UI elements are screen components the user can interact with. A checkbox, a menu
- Use *area* or *sidebar* (unbolded) to describe a particular group of elements on the current screen. Don't use *section*, *panel*, or *pane*. Check the [Products and user interface names](#product-and-user-interface-names) section for a description of individual UI areas.
| Usage | Example |
|:------------|:-------------------------------------------------------------------------|
| **Correct** | In the content area, right-click your message and and click **Edit**. |
| Usage | Example |
|:------------|:-----------------------------------------------------------------------|
| **Correct** | In the content area, right-click your message and and click **Edit**. |
| Incorrect | In the content panel, right-click your message and and click **Edit**. |
| **Correct** | From the navigation sidebar, click your profile picture. |
| Incorrect | From the navigation section, click your profile picture. |
| Incorrect | From the **navigation** sidebar, click your profile picture. |
| **Correct** | From the navigation sidebar, click your profile picture. |
| Incorrect | From the navigation section, click your profile picture. |
| Incorrect | From the **navigation** sidebar, click your profile picture. |
### User actions
@ -491,10 +513,10 @@ Modal verbs are auxiliary verbs that modify the meaning of the main verb in a se
- Use contractions to make your text more casual.
| Usage | Example |
|:--------|:----------------------------------|
| **Use** | you're / isn't / can't / it's |
| Avoid | you are / is not / cannot / it is |
| | Usage | Example |
|--|:--------|:-------------------------------------------|
| | **Use** | you're / isn't / can't / it's / can't |
| | Avoid | you are / is not / cannot / it is / cannot |
- Avoid the *'d* (had or would) and *'ve* (have) contractions, as these may be difficult to understand for non-native speakers.
@ -530,6 +552,14 @@ Modal verbs are auxiliary verbs that modify the meaning of the main verb in a se
- It's OK to use prepositions at the end of sentences (for example, *the user you're searching for*).
- Don't use italics or quotes to introduce a new concept; in general, don't use them on any part of the text (except when writing a [UI element](#ui-elements) that uses italics or quotes.)
- Use code formatting to distinguish parameters or options from the rest of your text when discussing them outside of procedure steps.
| Usage | Example |
|:------------|:----------------------------------------------------------------------------------|
| **Correct** | You can use the `Is Allowed` and `In options` to modify the permission scope. |
| Incorrect | You can use the Is Allowed and In options to modify the permission scope. |
| Incorrect | You can use the **Is Allowed** and **In** options to modify the permission scope. |
- Avoid sentence connectors, such as *therefore*, *hence*, or *as a consequence*. Rewrite the sentences if necessary.
- Don't use adjectives to describe a task's difficulty or time required.
@ -561,39 +591,6 @@ Use the Oxford spelling.
- Some examples of the Oxford spelling include: globalization, behaviour, centre, defence, catalogue, programme.
- If in doubt about any spelling, feel free to use the [Cambridge Dictionary][cambridge-dictionary]{:target="_blank"}.
## Word choice
Write in Global and Plain English.
- Don't use words that can be confusing for non-native speakers. For more details, see the [A-Z of alternative words :octicons-tab-external-16:][plain-english-alternative-words]{:target="_blank"} composed by the Plain English Campaign.
- Don't use Latin abbreviations like *e.g.*, *etc.* or *i.e.* Use an English equivalent, like *for example*, *and so on*, or *that is*.
- This list summarizes some common words and terms:
| Don't use | Use |
|:------------------|:--------------------------------------|
| cannot | can't |
| ensure | make sure |
| have to | must (see [Modal verbs](#modal-verbs))|
| in order to | to |
| in a way | so |
| need to | Imperative form of verb (or *should*) |
| drag-and-drop | drag and drop |
| Who, Whose | Replace the pronoun with the noun |
| & | and |
| time stamp | timestamp |
| web site | website |
| application | app |
| check box | checkbox |
| run (an app) | launch (an app) |
| cryptocurrency | crypto |
| Defi | DeFi |
| Dapp, dApp | DApp |
| MacOS | macOS |
| Macintosh | Mac |
| GNU Linux | Linux |
| Apple Silicon | Apple silicon |
| Intel (processor) | Intel processor |
<br>[:octicons-git-branch-24: Contribute to our docs][contributors-guide]{ .md-button }</br>
--8<-- "includes/urls-style-guide.txt"

86
docs/terminology.md
View File

@ -1,12 +1,48 @@
---
id: 20
revision: 2
revision: 3
hide:
- navigation
---
# Terminology
## Word choice
Write in Global and Plain English.
- Don't use words that can be confusing for non-native speakers. For more details, see the [A-Z of alternative words :octicons-tab-external-16:][plain-english-alternative-words]{:target="_blank"} composed by the Plain English Campaign.
- Don't use Latin abbreviations like *e.g.*, *etc.* or *i.e.* Use an English equivalent, like *for example*, *and so on*, or *that is*.
- This table summarizes some common words and terms.
| Don't use | Use |
|:---------------------|:---------------------------------------|
| cannot | can't |
| ensure | make sure |
| have to | must (see [Modal verbs](./style-conventions.md#modal-verbs)) |
| in order to | to |
| in a way | so |
| need to | Imperative form of verb (or *should*) |
| drag-and-drop | drag and drop |
| Who, Whose | Replace the pronoun with the noun |
| & | and |
| time stamp | timestamp |
| web site | website |
| application | app |
| check box | checkbox |
| run (an app) | launch (an app) |
| cryptocurrency | crypto |
| Defi | DeFi |
| Dapp, dApp | DApp |
| MacOS | macOS |
| Macintosh | Mac |
| GNU Linux | Linux |
| Apple Silicon | Apple silicon |
| Intel (processor) | Intel processor |
| Web3, Web3.0, web3.0 | web3 |
| DApp or dapp | dApp |
| avatar | profile picture |
## Status products and features names
Products and names include:
@ -66,53 +102,7 @@ This picture describes the main user interface areas for Status Web and Status D
## Icon names
This section lists the icons used by the mobile and web versions of Status. This list does not include the Status desktop icons, which will be updated to follow this convention after the Status MVP is released.
!!! note
If the icon shows a label in the UI, use the UI label. If the icon doesn't show a label in the UI, use the label name on this table. For more information, check out [Iconography](style-conventions.md#iconography).
| Label name | Icon |
|:---|:---|
| Activity centre | :iconset-activity-centre: |
| Add | :iconset-add: |
| Add contact | :iconset-add-contact: |
| Block User | :iconset-block-user: |
| Camera | :iconset-camera: |
| Communities | :iconset-communities: |
| Contact | :iconset-contact: |
| Delete | :iconset-delete: |
| Edit | :iconset-edit: |
| GIF | :iconset-gif: |
| Group Members | :iconset-group-members: |
| Image | :iconset-image: |
| Log out | :iconset-log-out: |
| Locked lock | :iconset-locked-lock: |
| Messages | :iconset-messages: |
| Microphone | :iconset-microphone: |
| More options | :iconset-more-options: |
| Muted | :iconset-muted: |
| Notifications unread | :iconset-notifications-unread: |
| Open lock | :iconset-open-lock: |
| Pin message | :iconset-pin: |
| Privacy | :iconset-privacy: |
| Profile | :iconset-profile: |
| QR code | :iconset-qr-code: |
| Reaction | :iconset-reaction: |
| Remove member | :iconset-remove-member: |
| Reply | :iconset-reply: |
| Send | :iconset-send: |
| Share | :iconset-share: |
| Sticker | :iconset-sticker: |
| Trusted | :iconset-trusted: |
| one | :iconset-one: |
| Two | :iconset-two: |
| Three | :iconset-three: |
| Four | :iconset-four: |
| Five | :iconset-five: |
| Six | :iconset-six: |
| Seven | :iconset-seven: |
| Eight | :iconset-eight: |
| Nine | :iconset-nine: |
If the icon shows a label in the UI, use the UI label. If the icon doesn't show a label in the UI, use the a name based on the icon's Figma description.
<br>[:octicons-git-branch-24: Contribute to our docs][contributors-guide]{ .md-button }</br>