When I worked at RIM (Blackberry), we had the luxury of having technical writers on staff. They were brilliant at yanking information out of engineering and organizing it into cohesive sets of documentation. Not all companies or departments can afford a good technical writers on staff, so we all need to pitch in and do it. What constitutes good technical writing?
I’ve written about one aspect of technical writing before in the Checklists and Runbooks article diving into when and why they are important.
Structure
Deeper system documentation is usually kept in some kind of “Wiki” or enterprise documentation system like “Confluence” these days. (Systems and procedures change too often to be in any kind of static form like hard copy, although at RIM, one of the tech writers developed a “Nutshell Book” with an O’Reilly knock-off cover!)
Documentation needs to have some kind of structure so the information is easy to find when required. I’ve seen company documentation in the past that was described by users as a “black hole” because once there, things were almost impossible to find when needed!
Thinking of the structure like a “table of contents” of a book can often help organize a set of documentation to make it more useful, manageable and accessible. I’ll have more on this in a followup article.
Why It’s Important
Good documentation is:
- scalable, available to all your colleagues, anytime;
- persistent, available if you are no longer available;
- asynchronous, people are not blocked waiting for an SME (subject matter expert) which could be you!
- relevant, unlike other forms of learning, colleagues are more likely to retain the information when they learn it while they need it.
Requirements for Good Tech Writing
Consider not only the purpose of the documentation, but also the audience. This improves the signal to noise ratio for the readers. The other factors I feel are important are:
- Accuracy – of the information provided
- Clarity – clear writing
- Accessibility – easy to find
- Conciseness – not overly verbose
- Correctness – correct spelling, grammar
- Consistency – consistent writing style
- Currency – goes with accuracy really
- Beauty – If it’s beautiful, contributions are more likely!
Test it !
Have a colleague check it. Another set of eyes can often see things you don’t and catch things like assumptions about the tacit knowledge of the audience. If it is a procedures document, see if they can follow the procedure.