writing principles

1. front-load important information
  weak: "in this document we will discuss the various configuration
         options that are available to users of the system"
  strong: "configure the system in config.json. key options: port, debug, log_level"

2. use active voice
  weak: "the configuration file can be edited by the user"
  strong: "edit config.json to configure the system"

3. be specific
  weak: "run the setup command"
  strong: "run: npm install && npm run setup"

4. show, then explain
  weak: "to start the server you need to run a command that initializes..."
  strong: "start the server:
           npm start
           this runs index.js with the default configuration"

5. use consistent terminology
  pick terms and stick to them.
  dont alternate between "config file," "configuration," "settings"

6. write for scanning
  users dont read - they scan.
  use headers, bullets, code blocks.
  put the answer first, explanation after.

