Writing rules
These rules apply to each page on this site. The source of the rules is ASD-STE100, Simplified Technical English (STE). A checker program, check.py, examines each page against the rules that a program can measure.
1. Meaning
- The STE text has the same requirements as the source text.
- Each requirement in the source has one equivalent statement in the STE text.
- If the meaning of a requirement can change in a rewrite, keep the structure of the source sentence.
- The source text is the normative text. Each page has a link to its source.
- Some source sentences are about the typography of the source. For these sentences, write "in the source document".
- Click the circled "i" icon in the text to open a "Context" panel at the side of the page. The panel contains explanation from outside the source. This text is informative only. Each panel has a link to its origin. The source text is correct when a panel and the source disagree.
2. Content that stays the same
Copy these items from the source with no changes:
- Mathematical expressions.
- Code, field names, constants, test vectors and command lines.
- The header block of a ZIP.
- Document titles and section headings. Thus links to a section stay correct.
- Names of persons, products, network upgrades and algorithms.
- Text that a ZIP quotes from a different document, for example a change to the text of the protocol specification.
- The reference list. The titles of other documents stay as their authors wrote them. Their punctuation stays the same also.
- Numbers, units and table values.
3. Words
- Use the approved words of the STE dictionary, with their approved meaning and part of speech.
- Use technical names for the objects of the Zcash domain. Examples are transaction, block, note, nullifier, mempool and consensus rule.
- Use technical verbs for the operations of the Zcash domain. Examples are mine, hash, sign, encrypt, decrypt, encode, decode, serialize, parse, validate, activate, spend and shield.
- Use one term for one concept. The term to use is in the term list.
- Use a maximum of three nouns in a noun cluster. A technical name is one noun.
- Write each word in full. Write "do not", "for example" and "that is".
Replacement words
The checker rejects the words in the left column.
| Source word | STE word |
|---|---|
| allow, enable, permit | let |
| ensure, guarantee that | make sure |
| perform, carry out | do |
| provide | give, supply |
| require, need (verb) | must, necessary |
| obtain, acquire | get |
| utilize | use |
| whether | if |
| which (relative pronoun) | that |
| however | but |
| therefore, hence | thus |
| prior to | before |
| in order to | to |
| e.g., i.e., etc. | for example, that is, and other items |
| might, could, would | can, or a statement in the simple present tense |
4. Sentences
- A sentence has a maximum of 25 words.
- A step in a procedure has a maximum of 20 words. Write each step as a command.
- A sentence has one topic.
- A paragraph has a maximum of 6 sentences.
- Give an action verb only to an actor. An actor is a person, or software that operates: a user, a sender, a miner, a node, a wallet, a verifier, an implementation.
- A document, a rule, a field, a value, a feature and a network upgrade are things. For a thing, use a state verb (be, have, contain, include, apply to, depend on), or the passive voice, or name the actor. Example: write "A sender can set an expiry height", and "The rule lets a transaction set an expiry height" is incorrect.
- Use the active voice when the sentence has an actor.
- Use the simple present tense for a rule or a fact. Use the simple past tense for a completed event. Use the simple future tense for a future event.
- Use a vertical list for three or more parallel items.
- Use an article (the, a, an) or a demonstrative adjective (this, these) before a noun.
The checker counts words as follows. A mathematical expression is one word. A code item is one word. A sentence ends at a colon. Text in parentheses is a different sentence.
5. BCP 14 key words
The key words of BCP 14 are in the source documents. Only some of these words are approved in STE. The STE replacements are in this table.
| Source key word | STE text |
|---|---|
| MUST, SHALL, REQUIRED | must |
| MUST NOT, SHALL NOT | must not |
| SHOULD, RECOMMENDED | we recommend that … |
| SHOULD NOT, NOT RECOMMENDED | we recommend that … not … |
| MAY | can |
| OPTIONAL | optional |
- "We" is the group of authors of the source document.
- Each replacement has a mark. Put the pointer on a marked word to see the source key word. Example: a node can remove the transaction.
- For a source key word in capital letters, the writer always uses the table.
- In some older documents, three of the key words are in small letters. For these words, the writer gives the meaning of the sentence in STE. The source word is in the mark. A "should" in small letters becomes "we recommend that" or a command. The word "must" is too strong for it.
- On a page that has marks, a link to this section is in the place of the BCP 14 paragraph of the source.
6. Term list
The writers add terms to this list as they write more STE versions.
| Term to use | Source words |
|---|---|
| expiry height | expiration time, expiration block height, expiry |
| block height | blockheight, height of the block |
| transaction | tx, txn |
| target block spacing | block target spacing, target spacing, target block time |
| network upgrade | upgrade, hard fork (when it means a planned upgrade) |
| activation height | activation block height, activation blockheight |
| implementation | software, client (when it means node or wallet software) |
| conventional transaction fee | conventional fee, standard transaction fee |
| unpaid action | unpaid logical action |
| adversary | attacker |
| block chain | blockchain |
| pull request | PR |
| ZIP draft | draft, proposal (when it means a ZIP that has no number) |
| Owners | ZIP Owners, authors (when it means the current owners of a ZIP) |
| ZIP Editors | Editors |
| calculate | compute |
| select | pick, choose |
| increase, decrease | raise, reduce, cut |
| change | modify, alter |
| send | submit |
| refer to | see |
| a maximum of, a minimum of | up to, at least (for quantities) |
| usually | normally, typically |
| have an effect on | affect, impact |
| start | begin, commence |
| at this time | currently |
| later | subsequent |
| previous | preceding |
| approximately | roughly, about |
| applicable | appropriate, relevant |
| different | distinct (when the meaning stays the same) |
| keep | retain, maintain |
| greater than | exceed |
| this ZIP | this proposal (for a ZIP that has a number) |
| create (a transaction) | construct |
| inbound connection | incoming connection |
7. Limits of this version
- The checker measures sentence length, paragraph length, verb forms, the replacement words and action verbs on things.
- The checker compares mathematical expressions, code and key word counts with the source.
- The authors of this site applied the STE dictionary from knowledge of the standard. A check against the licensed word list of ASD-STE100 is a later step.