mirror of
https://github.com/lightning/bolts.git
synced 2024-11-19 10:00:04 +01:00
77 lines
2.7 KiB
Markdown
77 lines
2.7 KiB
Markdown
# Basic checklist/stylesheet used for copy editing BOLTs
|
|
|
|
Contributions should comply with this checklist/stylsheet to maintain correct, clear, consistent, and concise BOLTS.
|
|
|
|
- spelling
|
|
- run `tools/spellcheck.sh --check [0-9][0-9]-*.md`
|
|
- update `.aspell.en.pws` with any missing words
|
|
- typos
|
|
- sentence structure
|
|
- sentence fragments
|
|
- run-on sentences
|
|
- dangling, misplaced modifiers
|
|
- consistent paragraph tense (e.g. past, present, future)
|
|
- passive voice (e.g. avoid 'we')
|
|
- use 'local/remote' terminology rather than 'us/them' or 'we/they'
|
|
- exception: `Introduction` section
|
|
- capitalization
|
|
- table of contents
|
|
- headers
|
|
- capitalize list items containing complete sentences
|
|
- commonly forgotten: 'Lightning', 'ID'
|
|
- distinguish between network and currency unit
|
|
- e.g. "The Bitcoin network transfers bitcoins."
|
|
- punctuation
|
|
- correct comma, colon, semi-colon, em-dash placement
|
|
- for conjoined items, use comma before conjunction
|
|
- e.g. 'this, that, and the other'
|
|
- appropriate use of parenthesis
|
|
- only use periods after list items if they contain complete sentences
|
|
- exceptions: `Requirements` lists
|
|
- abbreviations
|
|
- e.g., i.e., etc., a.k.a.
|
|
- formatting
|
|
- single spaces between sentences
|
|
- consistent use of _emphasis_, **strong**, `code`, CAPS, 'quotes'
|
|
- single line separators between paragraphs and page elements
|
|
- ensure correct header weights
|
|
- numbers and calculations
|
|
- spell out small (<10) amounts
|
|
- type digits and enumerations
|
|
- e.g. 'two 2-byte blocks set to 0s', 'one 4-byte block set to 1s', 'the other one is equal to 1'
|
|
- exceptions, e.g. 'non-zero', '1 byte in length'
|
|
- data measurements
|
|
- type digits for quantities of information, use hyphen when unit is an adjective
|
|
- e.g. 'a 32-bit block is 32 bits in length'
|
|
- for typed calculations
|
|
- space both sides of operators (except '^' and negative numbers)
|
|
- e.g. 5 - 3^2 * 4 = -31
|
|
- for calculation descriptions
|
|
- write out operators
|
|
- e.g. 1 less than 3 equals 2
|
|
- list structure
|
|
- 2 spaces before item
|
|
- indent 2 spaces
|
|
- `Requirements` sections
|
|
- colon after conditions
|
|
- comma before sub-items
|
|
- period at branch ends
|
|
- example:
|
|
```
|
|
A sending node:
|
|
- MAY do this.
|
|
- if this, AND this:
|
|
- SHOULD do this.
|
|
- otherwise:
|
|
- MUST do this,
|
|
- but MUST NOT...in this case.
|
|
```
|
|
- links
|
|
- broken links
|
|
- link text
|
|
- correct anchors/urls
|
|
- references
|
|
- format e.g. <sup>[1](#reference-1)</sup>
|
|
- tags
|
|
- consistent usage, e.g. [TODO:], [FIXME:]
|