On conciseness and technical writing, part two


I appreciate that technical writing that is explicit about its caveats, limitations, and expectations. It gives you a perspective from which to approach the subject matter. Here is an off-the-cuff template of what I'm hoping to see in my technical writing:

  • statement of purpose and context
    • what is it? what are the dependencies?
    • why was it made? why use it? why does it need to exist?
    • where can one find it? where is the documentation?
    • when is it from? (new, legacy, changes, etc)
    • who made it? who benefits?
  • limitations, caveats, expectations
    • this is a limitation
    • this is a caveat
    • this is an expectation
  • summary of important steps or points
    1. step one
    2. step two
    3. step three
    4. etc
  1. first step unabridged
  2. second step unabridged
  3. etc