Part 1: Let’s Write Technical Documentation, said no one ever…
This post is Part 1 of 2 that covers the writing concepts of technical documentation to help you get started writing. Stay tuned for more practical tips and information on deliverables in Part 2.
Purpose of Software Documentation
Requirements: Identify what is being built and verify stakeholders’ expectations are being met.
Design / Architecture: Define how the system will be constructed, describing how critical components fit together.
Code / Technical: Enable task completion and understanding.
Test Plans / Test Cases: Define the approach to testing; expose errors or demonstrate correct behavior.
End - User: Enable task completion; provide support and troubleshooting.
Plan and Research
What is the purpose of the document?
- If the document doesn’t have a purpose it shouldn’t exist
Analyze your audience
- Who will be reading this?
What do they already know?
- Why are they going to be reading it?
- In what environment will they be reading it?
- What is their state of mind?
- What do they NEED to know?
The Writing Process
- Organize your content and ideas — simple to complex, chronological, specific to general
- Create your writing plan by making lists or categories. If you find any that don’t directly relate to the purpose, take them out. Think about your writing format. Will you be using bulleted lists, graphics, charts or is there a style guide you need to be following?
2. Write the first draft
- Write. Follow your plan from step one. Don’t worry too much about grammar, formatting, word choice, spelling, or those types of things.
3. Review and revise
- Does it fulfill its purpose?
- Is there anything missing?
- Is there anything that can be omitted?
- What questions will the reader have?
- Is the writing easy to understand?
- Handle translations with languages
- Bundle up all the deliverables for the client (e.g. READMEs, web pages, PDFs, etc)
- Coordinate with the developers and other writers on the project
- Create a plan to update the documentation (i.e. bug fixes, new releases)
Writing tips and best practices
Accuracy in writing
“Fast is fine, but accuracy is everything”
“It takes less time to do a thing right than to explain why you did it wrong.”
― Henry Wadsworth Longfellow
Aspects of Accuracy
- Contains proper coverage of topics in appropriate detail
- Focuses clearly on the problem or solution
- Solves theoretical or practical problem
- Words are used precisely to express meaning
- Sentence and paragraph structure analyze topics effectively
- Technically accurate understanding and representation of the subject
- Depends on the writers knowledge of subject (research is VERY important)
- Introduction, table of contents
- Visual representations
- Descriptive headings
- Say what you mean
- Put it in context, What is the big picture?
- State the purpose
- Precede the document
- How does the document relate to other documents?
- Convey only the needed material
- Have a clear focus
- Use visuals rather than words
- Eliminate non-related words
- Be conversational in your writing, write the way you talk
- Be personable, show your personality
- Verb forms
- Mostly use present tense or future tense
- Keep the same verb tense throughout the document
- Communication and clarity are most important
- Keep contrast high
- Limit the number of fonts
- On the web, use web-safe fonts
- Use size 10 or larger
- Use ALL CAPS Sparingly
- Design for copy-and-paste
You can have the most beautiful document in the world; if users can’t read and understand it, it’s useless. Function over fancy.
Technical documentation is not the most exciting task, but a necessary one, since projects with incomplete, poorly written or no instructions can be frustrating . Hopefully these tips will help you write technical documentation with less stress and more confidence. Stay tuned for Part 2!