As technical writers, we prepare documents that contain technically accurate information. But, is that enough? Do we deliver documents that are technically accurate, but practically useless? The truth is: we often do.
In most cases, we deliver documents with the purpose to only support our products. The idea that documents serve as “troubleshooters” is incorrect. Seems we must plan our documents as the one-stop point-of-reference for our products.
In my previous post, I’ve discussed about refining the definition of quality in documentation. Technically, this post begins where I concluded that conversation.
Customer loyalty is dependent on how well we address our customers’ requirements. It is the need/want of our customers that drives their purchase decisions. Therefore, it is their needs/wants that should be the basis of our documents. Sadly, in most cases it is the product features, and not business implications of those features that drive our documentation.
We’ve talked about this before. We’ve noted that it is not the features, but the benefits that sell. I’ve even quoted it in my previous post. I see that there is a connection between “findability” and loyalty. Now, if it is brand loyalty (or product loyalty) is a question that I would like to address in one of my next posts.
I am acting team lead for my current project. And, although it is not the first time I am in the leader’s chair, the project has had a lot of learning for me. Also, based on my analysis, I have prepared a methodology, which I will share with you in this post. The methodology, which I’ve called the dartboard approach, has helped my team in overcoming a couple of big-sized challenges.
The first challenge was to update our documentation based on the new features and enhancements of previously released features in over 2000 pages. Now, for a team of three people (other writers are on the other products), it was difficult to incorporate changes (given the page count) in just 25 days. And, that includes Sundays!
The second challenge was to document the everyday changes as our “work-baby”–as we’ve termed it–learned to turn her head; begin to sit, crawl, and toddle; and eventually graduate in three streams. This meant loads of non-calculated, unplanned, and miscellaneous (but strategic) work, which was impossible to track back, nominate, or delegate. Phew! But, as I said, I learned a lot, and was just in time to attend the “graduation ceremony” of our work baby. We will discuss more about the challenges in Examples, in this post.
As I said, this post logically takes it up from where I concluded previously. Turns out, my new definition–to refine the quality parameters on the time taken by my users to find what they were looking for–worked! While the new definition did not relieve any stress with respect to the mechanical proofreading, it did help me a great deal in planning (and delivering) my documentation effectively during both the challenges.
The Solution–The Dartboard Approach
The following is the dartboard approach for your reference. Note that irrespective of what documents you plan, customer loyalty and user findability will always represent the two innermost concentric circles:
I’ll go back to where we started. At times, the gap between what we promise (to fulfill our customers’ requirements) and what we deliver (product and its features) is huge. Therefore, as tech writers, we should try to prepare our documentation based on what our customers require, and not on what our products are made to do.
I will pick an example from my current project. We have introduced a time-phased formula in our software for process manufacturers. The formula is useful in case of seasonal variations in formula. But, rather than explaining the formula and its features, we’ve provided details of the changes our customers observe when they implement this feature.
We followed a similar approach when we prepared the release notes for the GA release of our product. For the Known Issues section of our release notes document, we’ve prepared write-ups for the issues based on what our customers will encounter, and not based on the bottlenecks in our coding. That’s because our customers may not understand the code, but they will understand the business impact of the missing links. I remember reading a draft similar to the following:
“On account of differences in the code logic for recording the decimal values in the UOM_MTR_TAB1 table, the records are processed incorrectly, and a message similar to the following is reported: ‘Total lot quantity should be equal to required quantity <quan_mtr> for item <itm_db>.’”
Although the writer recorded exactly what was happening, but she missed the point. So to say, she lost the reader. Quite obviously, even if the SMEs agreed that the release note was “technically” correct, we could barely give any response beyond “Eh!”
Later, we finalized the following version, which I believe briefed our customer on what the issue was:
“On account of differences in the rounding-off for decimal values in the primary table for the Units of Measure (UOM) module, the system does not issue the items when the display UOM and system UOM are different, and a message similar to the following is reported: ‘Total lot quantity should be equal to required quantity <quan_mtr> for item <itm_db>.’”
Any write-up, or document, which explains the need for documentation, scores better on the dartboard approach as well as in the eyes of our readers.
Now, I will like to mention something. When I make a purchase decision, I have my reservations against product brochures. So to say, I rely more on reviews than on the marketing collaterals. When writing professionally, we tend to stress on what we have for our readers/customers, and not on what they might look for in our products. Considering the dartboard approach, we are missing the “point”. It makes sense to write based on the business benefits in features, and not mere describe the features.
I recall another example where the dartboard approach rescued us. We recently updated the write-up for the Create Planning Calendar form into our product. The feature provides a capability to assign work and non-work days in a calendar. The values are set as part of the implementation process, and by the time you bring your data live, you have your production vessels marked based on the production schedule you created using the feature. I am sure had I not thought of it through the dartboard approach, I wouldn’t have appealed my readers.
But, do I need to “appeal” them? Yes, I need to! But I also need to be grammatically correct, technically accurate, and make the information findable.
As I approach the end of this post, I recall having learned one easy-to-learn-but-difficult-to-follow lesson during my first stint as a sales rep-cum-writer: One customer is nine customers put together. I see how valid it is even in technical writing. If I can make my readers understand and follow what I write, I’ve done a satisfactory job.
I see my profile as that of a silent ambassador. My documents talk a lot about me, my products, and my value proposition (my promise). And, as I see it, my readers’ loyalty towards my products is only as good as my loyalty towards my profession.
Let me know your comments on the dartboard approach. I also am eager to know how it brings value to your content.