The Writing Principles

Have you ever come across a poorly written write-up? Have you ever felt that you could have written better? A couple of write-ups, which I read recently, drew my thoughts on writing about writing. I have always believed that anyone can write. But, if everyone can write, can everyone become a writer? I have explored this thought, and prepared a list (… which is not really an exhaustive one!) of guidelines that can help everyone write better. Read the full post.

Information Projection: Where Meet Information Architecture and Information Design

The new capability that we introduced into our flagship product helped me learn a lot about information architecture and information design. But, this post is about information projection. As I understand, it lies on the overlap of information architecture and information design. The post is also about the layers of information projection elements and the parameters that affect those layers. Click here to read the full post.

The Inverted Tree of Information

I will start this post where I ended the previous one: the inverted tree structure of information categorization. As promised, I will talk about my interpretations on some of the verses in the Bhagwad Gita, which is a great source of inspiration for me on both, personal as well as professional grounds. Click here to read the full post.

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.

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…