I can’t find a solid attribution to the title of this post, I only know it isn’t me. But I wish it were. I read it first in a Tom Clancy novel and they were talking about the stock market. I don’t say it nearly enough, and I’m talking about IT documentation.
Say what you want about “self-documenting”. Until that becomes a solid feature of an “AI” product, self-documenting isn’t. If you don’t believe me, find some code or configuration file you wrote 3 years ago and haven’t looked at since and tell me what it does and why. Yes, there will be a small percentage of cases where this will be perfectly clear, and to those few I say “now hand it to someone you have never met and see if they get the same information””. That percentage drops drastically.
Here are some of my thoughts on documentation that I hope will inspire you to create more and help you to make it as useful as possible with the least effort necessary.
Identify Customer-Required Documents at the Start of the Project
Customers often do not look for documentation gaps until near the time when they expect them to be completed. Ask for their specific documentation requirements up front. They may later want to expand that list, and acquiring the list at the beginning and publishing the list for customer review early in the project will allow for better prioritization when the project is nearing the end.
Start Documentation Early
Many initially successful projects can later be viewed as poorly delivered when proper documentation for enhancements and maintenance is incomplete or non-existent. Begin your documentation as early as possible with a full outline and then fill it in the details as time permits. This helps to reduce the project wrap-up stress in starting documentation from scratch at the 11th hours.
Use Technical Deliverable Templates
Templates help to standardize documents for easier reference and provide reminders of sections to include and approaches for presenting specific topics.
Start from a Blank Template
While it is tempting to start from an existing document, this can result in bad data being left in and verifications of details between designs being properly verified. One example is a project that had scheduled jobs that ended up overlapping because the team kept creating new documents from the existing documents and leaving the schedule table unverified.
Write Instructional Material with the “Eye of the Beginner”
There are few things more frustrating to someone trying to accomplish a specific task according to instructions to get stuck because their current results don’t match the instructions. Who they blame for this is often more of a reflection on their temperament than the instructions, and in IT it is fair to say that most of the time it is the fault of the instruction. Other than true technical writers (there are many in tech writing roles who are really either copywriters or editors and not true technical writers), most people who write documentation do so from the perspective of having already accomplished the task. While being able to do the task can be very useful in writing documentation, knowing how to look at the task through the eyes of someone who does not is the key to being a good technical writer. Follow the steps of your own documentation exactly from the point of view of having never done it before (VMs are great for this), and revise your documentation every time you find a missing step or a concept that is only clear with experience of having already accomplished the step or task. If you have a hard time doing that, have people with no understanding of your subject follow your documentation (without you present!) and provide feedback.
Avoid Unspecified Nouns
Unspecified nouns are words such as this, that, they, and it. The use of unspecified nouns can be confusing if there is more than one possible interpretation. While you, as the communicator, may only see one meaning for what is referred to by the unspecified noun, a reader or listener may not.
For example, “they may not understand the purpose of the link” is clearer as “stakeholders may not understand the purpose of the link” or “users may not understand the purpose of the link”, both of which may have different meanings.
While it may seem excessive and repetitive to do so, repeat the name of the thing you are talking about rather than assuming that everyone will know what this is meant by that.
Note, this has nothing to do with use of preferred pronouns. I was using they and them for years and wish I had contact information for the teachers and editors who kept insisting I use he and his when referring to an unspecified actor or reader so I could send them an I-told-you-so emoji.
Validate Guide Documents
The value of a guide is that people should be able to use the guide to complete the tasks it describes without assistance. First validate it yourself by following your document exactly as you have written it. Then have someone that will be a consumer of the document go through and follow the guide, having them make notes with Track Changes turned on. Bonus points for getting someone that has little understanding of the supporting technologies to do the validation.
A Picture Should Be Worth a Thousand Words
Screen shots should be used when they enhance understanding, allowing fewer words to describe the full details. They are not a replacement for all descriptions. At a minimum they should have a caption.
When values need to be entered in a screen shot, always include the values as text so that readers can copy/paste the values. Command line entries should use a style indicating they are commands rather than a screen shot showing the command, again to facilitate copy/paste and also because:
Is not clearer than:
Type this here
Update the Document Reference Links as You Work
Throughout the project you will need to find information online relevant to the solution. In addition to maintaining your own reference bookmarks, whenever you find a URL particularly useful to the solution add it to the Reference Links section of the project documentation. If you do not own the document, send the links to the team member that does for inclusion.
Share Your Knowledge Regularly
Hopefully your employer and/or client have a Knowledge Management system. At a minimum, the following milestones should be a reminder to contribute to this shared knowledge base:
- Completion of a project
- Completion of a key deliverable
- Solving a difficult issue
If you find it difficult to remember to make KM contributions following these events, set a regular reminder (weekly if not daily) to think about your activities and accomplishments and if there is something that is worth sharing, then do so.
© Scott S. Nelson
