Skip to content

Latest commit

 

History

History
76 lines (74 loc) · 2.72 KB

.copy-edit-stylesheet-checklist.md

File metadata and controls

76 lines (74 loc) · 2.72 KB
Raw

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. 1
  • tags
    • consistent usage, e.g. [TODO:], [FIXME:]