Premise
The quality of documentation is often determined on parameters that are subjective in nature. These parameters are largely based on the time taken to complete the documentation.
Analysis
It is natural for our readers to assume that the issues they encounter, are documented in our guides, and are easy to understand and implement. As a tech writer, I see that the documentation is only a medium for my readers to resolve their issues. After all, who has the time to read entire documents?
This is a typical case, but the challenge for us (as tech writers) is to think like a developer/tester, write like a writer, and read/rewrite like a reader. Additionally, we often encounter new challenges (new product), responsibilities (Switching roles between writers and editors), and tools; and, all of that put together under a new deadline for the new projects.
Personally, the challenging profile is just one of the many reasons I like being a tech writer! But the fact is, amidst different projects, products, tools, and deadlines, the idea of “getting understood correctly” doesn’t become any easier to implement.
Reference
The project that we delivered in the last month seemed never-ending. And, we aren’t the only ones who felt that way. Projects that are entry-level, dynamically designed/managed (agile), or handled by bad managers often end up that way. Ours, was an entry-level product (first GA release) and it registered modifications in almost every meeting. As a result, we were late in delivering the documentation.
It is worth a mention that my previous post, Wabi-Sabi and Technical Writing, which underlines the need for perfection in technical writing and received an overwhelming response (I cannot thank you enough!), concluded the following points in its discussion threads:
- All of us felt that timely delivery, and not perfection, was the preferred choice.
- Almost everybody agreed that the reader, and not the content, was at their focus.
- Majority of us agreed that it was impossible to achieve perfection in technical writing.
- Some of us thought that it was better to have perfectly drafted documents than to have perfect documents. We will discuss the difference in some other post, but not today.
- Some of us thought that perfection in documentation was subject to its need, timely delivery, and cost effectiveness. So, if your documentation served the readers in time, and contained possibly all the information the readers were looking for, the documentation was considered perfect.
- Time remained a key factor for all of us.
- We acknowledged that our documents would need frequent revisions, frequently.
I recall that we’ve discussed another issue, in one of my previous posts, Differentiation vs. Standardization. I remember quoting the difference between features and benefits. The whole point of that discussion revolved around the fact that the benefits, and not the features, sold products.
Coming back to where I began this conversation, I see that the central idea for effective documentation is not in instructing readers about what the product can do, but in telling what they can do with the product. I, therefore, tell my reader what else they can do using the newly added features.
Conclusion
Based on my analysis/observation, I can conclude that the quality of documentation should be determined on the time taken by the readers to successfully locate the remedies to their pains, and NOT on the time taken to complete the documentation.
As discussed earlier, it is obvious for readers to think that the document contains the information they require. And, as tech writers, we must make sure that we:
- Do not beat around the bush.
- Keep our documentation to the minimal. (And, not minimal documentation!)
- Keep the key sentences in the beginning of the paragraph.
- Mean what we write, or at least write what we mean.
- Take a note before we write. And, rewrite after we’ve written.
- Use proper formatting for our readers to locate either their pains or the remedies.
- Write clearly, without errors.
You may provide the documentation, hence prepared, to your trainees to check how effectively you’ve documented. But, your readers are still the best judge of your documentation.
I would like you to respond based on the post, so that new points can be added to the handy list we just discussed. Have a nice day!
The Wordsmith 