How “Technical” Should Documentation Be?

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.”

Technical Communicator: The New Branding Person

Last month, I got a chance to read from some of my old books. I am a marketing graduate. So, while I read some random pages from the marketing domain, I could see that the learning matched to technical communication as well. But, how could the lessons on branding teach anything about technical communication? In this post, I try to explore this question to help improve my understanding.

Reduce: To Improve

This post is about progressive reduction, which is what I’ve recently read about. From what I have gleaned, progressive reduction is about those gradual changes (mostly reduction) in the UI elements that relate to your time-lapsed incremental cognition of a product. In other words, progressive reduction is in continuously adapting the UI elements of your product based on the gradual improvement in its usability. Read the full post.

The Key Elements in Technical Communication

The bent towards information design is on account of its applicability – A picture, as they say, is worth a thousand words. The use of graphics minimizes the use of content. Rather, it squeezes the underlying message of the content into a graphics. Despite the usually observed bent of mind, I believe that the key elements of Information Design and Technical Communication are the same. Here’s how…

The All-Important: Redundancy

Redundancy is inseparable. But, it is still important to make mutual sense. Your reader wants to search for content that resolves the purpose of the search. But, that sadly isn’t always on our list of goals. This article tries to see the possible definition and cause of redundancy, and suggest the probable solutions to resolve or avoid it. Click here to read the full article.

Note: The stub contains the link for the article, which is placed under a separate tab. Access the article either directly from the related tab or through the link in the stub. The stub is for only referential and record-keeping purposes.

Parallelism: Comprehension is Parallel to Reading

This article focuses on the use of uniform writing structure and tone in order to improve comprehension and promote correct action. The thought of writing this post came to me as I searched through the pages of the legacy documentation for one of our products. I think the idea of maintaining a uniform structure is important, yet (often) ignored. Read the full post here.

Note: The stub contains the link for the article, which is placed under a separate tab. Access the article either directly from the related tab or through the link in the stub. The stub is for only referential and record-keeping purposes.

Is Technical Writing Skill or Ability?

I often say this to myself: Anyone can write, but everyone cannot become a writer. But, when we can (and do) learn to write, why can’t we learn to become writers?

Language is a skill, which can be learned and mastered over a period of time. We must learn to follow the rules. Although subconsciously, notice that we almost always associate “writing” with “ability.” But, if that is true, why is writing (which is an ability) regarded as a profession (which is a skill)?

I recently read that writing features in a list of top 15 jobs that have survived for centuries, and assume it will continue to be there through the next century. This contradicts our current thread of discussion. Is technical writing really a skill or an ability? We can look to answer that question. But, first we must find if there are any rules for writing.

Now, the answer depends on what you would like to write. If you are writing prose, your work – in general – should be involving and interconnected, and contain a story. If you are writing verses, the work should have flow and be rhythmic and soulful. Still, none of these are rules. None of these [guidelines] can either be taught or evaluated. It is only the response to your work (or if I may say the reader connect) that can be evaluated.

So, can our work be evaluated based on the response? Certainly, it can be! And, it is a skill to drive the intended response. And, hence writing is a skill as well; a skill, which has some underlying principles, guidelines, and rules that govern the overall structure and quotient of impact and usability.

My take? I think, as I try to answer this question, the following points become noteworthy:

  • It takes a lot of practice to practice technical writing.
  • You need to be a writer (or think like one) – have a natural flair for writing, as they say!
  • You should love using technology.
  • It takes a lot of reading. But, read quality material.
  • You should enjoy walking on the thin line that separates skills and abilities

One last thought: You can have the inborn ability to smell the ingredients, but it still takes some learning to hone to skills of cooking. You can have the inborn ability to understand the poetry, but it still takes some learning to home your singing skills. On the flip side, you need to have some inborn qualities that match with your skills to create the “X-factor.” So, my take: Skill is to language; Ability is to writing. And, technical writing is skill-oriented ability.

Tech Comm and the Glossary of Biz Economics

Premise

In the regular classes on Business Economics, during my graduation, I learned about certain concepts that still apply. Two of such concepts, Buyers and Users, are applicable in technical communication to a great extent.

Can those concepts lend any insights to us? Do we prepare our documentation considering the buyers or users? Or, do we concentrate on merely describing the features? The discussion follows in this post.

Observation

The easiest way to begin the conversation is to see what demarcate buyers and users.

It is strategic to choose which side you represent as a technical communicator. At large, all of us fall on the same side of the table – the sellers. We obviously don’t “sell” our content, but we do contribute (both actively and passively) to the sales cycle. Deep down, however, we aim to write from the point of view of the buyers and users. Note that I am using an “AND” between buyers and users.

I prepare and release technical documentation, just as any of you do. And, like you do, I too focus on what my company’s products deliver. But, the basic concepts of Business Economics help me demarcate the buyers and the users.

Definitions

The same demarcation that applies to Customers and Consumers, applies to buyers and users as well. Consider the following introductions to customers and consumers, based on what I have gleaned from the subject:

Customers. They may or may not use the product (and hence may not always qualify as end users), but they are the ones who buy. They implement a purchase decision. They influence the purchaser, and hence the purchase decision. They do not consume the products but can use the services and hence can impact your communications. The brand-level changes affect their perceptions.

Consumers. They use the product but are not necessarily the ones who buy. They either feel or create a need to purchase. Therefore, they are the ones who create and govern the purchase decisions, but under the influence of the buyers. They consume products and avail services. The feature-level changes affect them. They mostly know what they need.

Analysis

The points mentioned above are generic, but they communicate the scenario effectively. Let us now take an example to further outline the comparison of behaviors. Pick, for example, a health drink for children; Let me define it as “NutraChamp.” As customers (or buyers, in this case), you are affected by the brand philosophy (or value proposition) of the product.

But, the fact that the product is available in the flavor of your choice, which is a feature-level change, will affect you only if you are the consumer (or the user) of the product. The choice to go for a particular flavor, or even color of the packaging will belong to the consumer, but the decision to finally purchase it will still belong to the customer. And, in all probabilities, the purchase decision will not be governed by the color of the packaging and the flavor, but the information supplied with the product. This is where documentation plays its part in the sales cycle.

The information supplied – in this case, the supplements fact sheet – plays a strategic role when purchasing a product. For technical communicators like us, it is therefore important to understand the buying behaviors to communicate only what contributes to the learning curve of our customers as well as consumers and hence affects their purchase behaviors.

Conclusion

In similar situations, I focus on providing what my customers need. Additionally, my documentation becomes more “sellable” if I also include what they want. My learning, from the Business Economics class, has paid off! Need is extremely important, and hence, in our example, if the NutraChamp health drink contains a combination of health benefits, taste, and flavor, both the buyers as well as the users will be happy and satisfied with the purchase decision.

As a marketer, I might think differently, but as a technical communicator, I will try to communicate the health benefits, by providing the supplements fact sheet, and miscellaneous documentation, if needed.

I understand that as a technical communicator, I do not write in the marketing terminology. So, the purpose of this post is not to tell you to package and present wants as needs to buyers and users. But, based on our interaction so far, it is not difficult to assume that our documentation should contain feature-centric, benefit-oriented information.

I do not intend to tell you to make documents more “sellable”, but when the documents should address the needs as well as wants, the points mentioned above can come in handy.