lightning-bolts/.copy-edit-stylesheet-checklist.md

Basic checklist/stylesheet used for copy editing BOLTs

Contributions should comply with this checklist/stylesheet 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. ¹
• tags
  • consistent usage, e.g. [TODO:], [FIXME:]