mirror of https://github.com/status-im/specs.git
95 lines
3.2 KiB
Markdown
95 lines
3.2 KiB
Markdown
|
---
|
||
|
|
layout: default
|
||
|
|
permalink: /style-guideline
|
||
|
|
title: STYLE-GUIDELINE
|
||
|
|
---
|
||
|
|
|
||
|
|
# Style guidelines for Status client specifications
|
||
|
|
|
||
|
|
- [Spellcheck](#spellcheck)
|
||
|
|
- [Markdown Verification](#markdown-verification)
|
||
|
|
- [Language Mode](#language-mode)
|
||
|
|
|
||
|
|
## Spellcheck
|
||
|
|
|
||
|
|
To run the spellchecker locally, you must install [pyspelling](https://facelessuser.github.io/pyspelling/).
|
||
|
|
|
||
|
|
It can then be run with the following command:
|
||
|
|
|
||
|
|
```console
|
||
|
|
pyspelling -c spellcheck.yml
|
||
|
|
```
|
||
|
|
|
||
|
|
Words that should be ignored or are unrecognized must be added to the [wordlist](./wordlist.txt).
|
||
|
|
|
||
|
|
## Markdown Verification
|
||
|
|
|
||
|
|
We use [remark](https://remark.js.org/) to verify our markdown. You can easily run this tool simply by using our `npm` package:
|
||
|
|
|
||
|
|
```console
|
||
|
|
npm install
|
||
|
|
npm run lint
|
||
|
|
```
|
||
|
|
|
||
|
|
## Language mode
|
||
|
|
|
||
|
|
- Specifications SHOULD use formal technical language (*different from academic language*).
|
||
|
|
- Where appropriate, language SHOULD NOT use personal pronouns.
|
||
|
|
- Avoid using the [passive voice](https://en.wikipedia.org/wiki/English_passive_voice) when being specific.
|
||
|
|
- In places where the passive voice is appropriate but makes the subject ambiguous, append the passive voice with "by `subject`". Alternatively restructure the sentence to be in the active voice adding the sentence subject.
|
||
|
|
|
||
|
|
For further reading on writing technical documents please read the Google Technical Writing article on [Active voice vs. passive voice](https://developers.google.com/tech-writing/one/active-voice).
|
||
|
|
|
||
|
|
<details>
|
||
|
|
<summary>Examples:</summary>
|
||
|
|
|
||
|
|
### Personal pronouns
|
||
|
|
|
||
|
|
Informal:
|
||
|
|
>In this specification, **we** describe
|
||
|
|
|
||
|
|
Formal:
|
||
|
|
>This specification describes
|
||
|
|
|
||
|
|
Informal:
|
||
|
|
>If **you** want to run a Waku node and receive messages from Status clients, it must be properly configured.
|
||
|
|
|
||
|
|
Formal:
|
||
|
|
>A Waku node must be properly configured to receive messages from Status clients.
|
||
|
|
|
||
|
|
### Passive voice
|
||
|
|
|
||
|
|
Passive voice:
|
||
|
|
>a corresponding confirmation **is broadcast** by one or more peers
|
||
|
|
|
||
|
|
Active voice:
|
||
|
|
>**one or more peers broadcast** a corresponding confirmation
|
||
|
|
|
||
|
|
In the case where the object of the sentence needs to be highlighted or given prominence the passive voice is appropriate.
|
||
|
|
However, pay attention to not introduce an ambiguous subject if communicating specific information is your goal.
|
||
|
|
|
||
|
|
### Appropriate use of the passive voice
|
||
|
|
|
||
|
|
>The Batch Acknowledge packet is followed by a keccak256 hash of the envelope's batch data (raw bytes).
|
||
|
|
|
||
|
|
The subject of the sentence is "a keccak256 hash", but the sentence wants to highlight the Batch Acknowledge.
|
||
|
|
|
||
|
|
### Ambiguous subject
|
||
|
|
|
||
|
|
In many cases sentences written in passive voice may be grammatically correct but hide that the sentence lacks a specified subject.
|
||
|
|
|
||
|
|
Ambiguous:
|
||
|
|
>A message confirmation **is sent** using Batch Acknowledge
|
||
|
|
|
||
|
|
Active specific:
|
||
|
|
>**A node sends** a message confirmation using Batch Acknowledge
|
||
|
|
|
||
|
|
Passive specific:
|
||
|
|
>A message confirmation **is sent by a node** using Batch Acknowledge
|
||
|
|
|
||
|
|
Notice that the ambiguous sentence infers or omits the subject. Making it unclear what or who performs an action on the object of the sentence.
|
||
|
|
|
||
|
|
In the example ambiguous sentence it is not stated what or who is sending a message confirmation.
|
||
|
|
|
||
|
|
</details>
|