Metaphorically, the moon is considered as the classic epitome of beauty in any Indian poetry. Any creation that describes about a woman, will compare her beauty with the moon. Note that the metaphor that a woman looks better than the moon is because the moon, when closely observed, has marks, but the beauty (the facial expressions and the dignity) of a woman is without marks – such perfect is her beauty. What a beautiful expression! Consider the marks in the picture, which I captured (though not for this article) on the full moon night of November 17, this year.
This makes me wonder if there is anything worth calling perfect in technical writing. Although we may not metaphorically compare our documentation with the moon, but we sure can look at our internal standards and tell if we did a great job.
So, is perfection possible in technical writing?
The documentation for one of my previous stints contained basic, school-level English. Not that the language was incorrect, but it did not match the image of the company – the documentation contained numerous examples of how one should NOT write. And, it was not the only company with such a shift of focus. Within last six years, I have seen the “good enough” documents play the “perfect fit”. The point is of priority, which in most cases is timely delivery, and not perfection; most of them haven’t been serious about their documentation.
Note that “good enough” neither means “not perfect” nor does it mean a document, which is full of errors. It only means a document that solves the purpose for that point in time. Also, errors in our documents have meanings that are subject to context, interpretation, person, and time. So, an error for me may not be an error for you. Or, a word may mean differently for me (or you) in two different situations.
In her recent post, Michelle agrees that it is impossible to achieve perfection in technical editing. And, I assume it applies for technical writing in the same way. The documentation, which I have seen in a lot of cases, or the “good enough” documents that you might have come across match what the Japanese term Wabi-Sabi stands for.
Wabi-Sabi is the universal truth of seeing beauty in imperfection. I interpret this as an ongoing pursuit for perfection – that the beauty about life is that it is imperfect, impermanent, and incomplete. There has to be something in it that has influenced the life of Jack Dorsey (the co-creator of Twitter) to a great extent. [Source: The Internet.]
I tried to find a common thread in Wabi-Sabi and technical writing. Look what I observed, realized, and gleaned!
Accept, but don’t surrender. Writing is a tough job. There are a lot of things that you can see, touch, feel, know, realize, encounter, do, think, and yet cannot pen-down. Your writing, therefore, must be as close to the happening as possible. Write only what you see, observe, verify, or are able to reproduce in that scenario. But, don’t waste too much time in making your write-ups perfect – By the time you manage to edit your write-ups, chances are, your company will have changed or improved the feature.
A month back, I worked with my colleagues from the creative writing department, for our corporate blog. I assisted them to improve the content quality. As it turned out, they had to remove some paragraphs from their write-ups. The features they prepared their write-ups on, have now been removed from the base build.
Feedback: feed-forward. You have two ears, but only one mouth – So, listen twice as much as your talk (or write!). Use feedback wisely – improve your documentation to ensure that the readers’ feedback is incorporated. This makes your documents accurate.
Some of the troubleshooting guides, web sites ask you to rate their information. Closed-ended questions like, “Was the information useful?” helps them gather feedback on improving their content. Consider the following picture, which is a representation of the feedback pages on web sites like Microsoft.
Write less; rewrite more. (F.L. Lucas, Style. Cassell, 1955). Yes, I know; it’s normal for us to feel that our first draft is our final draft, and that no modification can possibly be made. But, to avoid any chances of mistakes, I review my documents the next morning. In most cases, I have a better version by the afternoon. I also use other techniques, such as the following, to judge how accurately I write: I print what I write, I ask others to read what I write, or I take a break (and read something else meanwhile) and then come back to the content.
During my previous stint, we had an eight-stage approval process. Each of our stage involved reproducing the issue to cross-check and verify the results. In my current stint, I make sure that I update the developers and testers with the results before I begin preparing write-ups for the issues. In case the issues are minor, cosmetic, or can be fixed before the product is released, we do not include them in our final documentation.
Rome wasn’t built in a day. And so isn’t good documentation, which requires time (and a number of iterations). Before we release our documents, we make hundreds or thousands of gradual improvements that help us ensure higher levels of quality in our documentation. The point is, if we stop, we perish. To continue to grow, we must continue to go.
When preparing documentation, I regularly update my documentation standards to incorporate the feedback of my colleagues (and customers, in some cases). This makes documentation easier and faster.
Today, in the computer, technology industry everyone seems to be talking about Agile programming environments. Agile, which is about incremental development, is a version of Wabi-Sabi. We perform, we check and observe, and we improve. Even patch releases of software products are examples of Wabi-Sabi.
The four walls of premise. Make sure you build a premise for your documentation. If you cannot describe everything your product CAN do, then just describe what it CAN’T.
During my previous stint, I wrote release notes for our flagship product. And, for some of the write-ups for the fixed-issues section, I never wrote what was fixed. I only wrote what our customers encountered when the issue was raised. Now, this is a classic case of the “just good enough” documentation – we never mentioned more than what our customers could understand/wanted to know.
I believe, documentation can never be complete, perfect. But, we can make sure that our documents are updated frequently. We may never be able to cover everything that’s there to cover, but we can document what our customers seek. Now, I am sure that there is hardly any difference between documents that are “just good enough” and documents that contain the information, which readers seek.
One last point. It is hard to accept imperfection, but perhaps it is harder to achieve perfection in technical documentation. There are a lot of unanswered questions as I approach the end of this post:
- As observed in most cases, readers complaint only if they come across bad drafts. Isn’t then the “good enough” documentation a case of trail-error, since it is difficult for us to assume the level of knowledge of our readers?
- Do “good enough documents” stand apart from the documents that are overloaded with information?
- Does technical writing have a room for Wabi-Sabi? From where I can see, there is a room for Wabi-Sabi, only if the information provided is correctly drafted and verified.
- Exactly how much of Wabi-Sabi is acceptable in technical documentation? I do not know the answer.
- Is there any difference between “error-free” documents and “perfect” documents? I believe there is! But, do we realize that gap that often? Like some of you, I too have released “good enough” documents in past, but that was a risk we had to take. What about the reader-centered approach? Is that not important?
I wish to become wise enough to find answers for these questions… “I wish”: Wabi-Sabi.