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
- step one
- step two
- step three
- first step unabridged
- second step unabridged