In a recent casual coffee-table conversation in our office, one of my colleagues asked this question to the tech-writing group. And, none of us had satisfactory answers. That’s because each of our reader has a unique, different level of knowledge. In fact, even the tech-writing team members in my office do not have the same level of knowledge about the company’s products. So, how do we determine the “technicality” in our documents?

About a year back, Colum McAndrew wrote on a similar topic. According to him, the best way to handle the user-assistance question is to not think in terms of “technical” or “end user” at all, but to “think of the audience as a whole if we are to answer this question.”

In my current stint, the company’s software products cater to small and medium-sized process manufacturers. When we began writing for the first GA release of one of the company’s products, the one rule that my team lead told me to strictly follow was: “Make your write-ups as easy as possible, because you are writing for the small-scale manufacturers. They certainly have the need, but they may not always afford the best of talent.” In few words, he said a lot about the clients, just as he said about our documentation.

To me, the answer to our question lies in my team lead’s statement – an easy and simple statement. We were fortunate to know who we were writing for – not all of us are that fortunate – still, that didn’t come as easy for us. That’s because our products are too complex. And, here’s what we did to ensure intended granularity in user understanding and experience:

• Instead of giving one manual for the complete product, we distributed (roughly) 1500 pages of content into eighteen different, module-specific user manuals. Today, after about a year-and-a-half, our company has begun following module-based licensing, where the users get to use only those features they pay for. So, spreading the content has had many advantages: the manuals open up quicker; locating content has become a lot easier; and, of course, the users have a “psychological” advantage of looking into a lot lesser number of pages for information.
• We prepared task-driven documentation. So, users did not have to search based on the screen names, but on what they wanted to do with the software. For example, rather than searching for the theoretical cost features, they could now search for cost estimation and rollup capabilities.
• Mostly, the technical teams prepare the release notes. And, we get to get our hands on the notes only when they are unable to frame words. But, whenever we are fortunate enough, we make sure that we skip the technicalities. That’s because, the readers don’t notice anything that happens in the backend: They only notice the end result. And, that’s exactly what matters to them. So, instead of documenting the changes, we document impact of the changes.
• Another change in documentation was with respect to grouping of information. Documenting issues is not important, but finding those is. Also, finding the information is not important, but using it is. On similar grounds, for one of the product releases last year, I made a successful experiment. I created a topic-based troubleshooting guide. This helped the readers easily locate the information, and later use that information to troubleshoot their issues. Consequently, the number of tickets greatly reduced. It saved a lot of time (and money) for our company.

There is no specific formula to determine the amount of “technicality” that should go into documents. I’ve realized that as long as I can back the technicalities in the documentation with “benefits,” and make business sense for the readers, I can afford to be “technical.”