Shubham Singhal, Fiserv
February 15, 2021

While people say, ‘Content is the King’, technical writers know the pain that people rarely read their work. Despite the tremendous efforts, there is no or little success in motivating people to read. So, where is the gap? What is the thing that writers miss?

I am not sure that the problem persists with the writers. If they are doing so much hard work, they must have considered all the variables to improve the readability. I mean look at the conferences, papers, and interactions that are happening at the global level. With so much information and thought exchange, it is virtually impossible that something was not tried.

On the other hand, when I look at the organization’s hierarchy, I observe something interesting. The business leaders understand the importance of communication so much, yet they place a technical writer’s team with the development team. Let me explain my point. A business sells a product to solve a problem/requirement. The outside-in approach explains this in great detail. First, we ponder on what problem someone has, then we talk about how we are solving that problem. However, a technical writer’s team is often told about the new features without making them understand the problem. So, everything a writer does never suffices the expectations of the readers.

Tell me one thing. Microsoft Word is one of the most used applications, right? And we believe that being a product of Microsoft, it does have great help documents. But, when we want to search for something related to it, do we go to its help manuals? If no, then why do you think that people will read your document. Okay, let me ask this way: What exactly do you search on Google while looking for some help?

By now it is evident that people search for what they are looking for. So how can we leverage what our leaders know and use the principles of communication for effective documentation? Let’s see the following example:

Mr. John is a technical writer in his organization. In his magical company, he works directly with the product owners and attends the SOW/requirement meetings. In those meetings, he gets to know the problem first and then how the company is solving the problem. Through the series of meetings, he also knows all the things that could have gone wrong and right. John then attends the developer’s meeting to understand the product feature, its flow, and basic user details. Then he starts formulating the document.

  • He starts with ‘What’ or ‘How’? This is typically how a user searches for help on the internet. Hence his document reflects at the top of search results.
  • He introduces the problem of the customer. Hence, the customer knows in the first paragraph that his document is of use or not.
  • John continues with the benefits and limitations of that feature and sets the expectation of the reader.
  • He continues with the steps that are no brainers. Readers exactly relate the steps with what they are seeing in the application. Currently, the reader doesn’t want to know the description of each thing. He wants to simply follow the direction.
  • In the end, John presents the results. The reader gets the feeling that he achieved something.

So, do you think John is using the right approach? If it were you, how differently would you have done it? In general, the document structure in an organization follows the highest standards of integrity, compliance, and standards. And the audience has always refused to even give them a glance (unless they are security-critical). And that’s because a document boasts about the product, and not about the requirement of a user.