By, Nivedita Aggarwal

The very reason why the technical writing community emerged as a separate function is to write ‘useful’ technical information. However, during several recruitment interviews, discussions with industry colleagues, and interactions on various forums, the majority of the topics seem to revolve around tools, styles, writing standards, publishing layouts, and processes. Our emphasis on ‘usefulness’ of content seems to have taken a backseat.

This article explores the reasons why technical writing seems to have strayed from the main objective, and suggests possible solutions to bring back the focus to stand out as a distinguished function.

One of the primary reasons could be the culture of quality assessment. Being a ‘writer’ in general, we know that any visual discrepancy attracts more attention. For example, if the code block is not following a certain style, it stands out in a page for someone who is reviewing. Similar argument holds good for pagination. For a writer, it becomes important that they do not get any red marks on their document. It requires them to focus more on the standards set by the organization – ‘Am I using active voice?’, ‘Am I using the right template?’, ‘Am I creating a pleasing document?’, and so on.

• Have usefulness as an aspect to cover during content development. This is beyond user analysis that we conventionally do. The usefulness of content includes context – is the product area or technology new, are the tasks routine or done once in a while, and so on. The cheat sheet for usefulness would end up being specific to each product to help during the content review process.
• Keep the standards and templates simple – less is better. Having more options would ensure that the core responsibility and focus is on producing useful content. If you see Github, it’s growing significantly as a community for open source products and components. You will also see some great documentation there by the developers. They don’t have all the fancy styles and formats that are usually considered for documentation. Nevertheless, their content is highly useful.
• Chunking does not mean breaking. Sometimes chunking can lead to highly fragmented content which may not convey the unit of thought or action. Review your information mapping standards and update if required to accommodate correct content flow.
• Organize critique sessions. ‘Should this sentence even exist?’ Having regular team reviews where you pull up a document or a piece of content and challenge the very existence of content right from the sentence level. This would help improve the overall usefulness. You might end up critiquing half a page of content, which is fine. Having such sessions help the team move more towards writing useful content for their own projects.

The second aspect is the way a technical writer is introduced to the product. Most of the product trainings do not focus on the context of the product area or the user base. Blanket statements like, ‘this is used by administrators’ is not good enough to write useful content.

• Answer who and when questions. Do not end the who part as ‘administrator’, ‘novice to IT’, etc. Who also includes the context and then answer ‘when’ to it. For example, an administrator can be using a product, but they might be new to the technology that you are talking about. The breadth and depth of content varies based on the administrator’s familiarity with the technology. This helps us understand what information the administrator at any level of understanding may require to work with the product. You can document any prerequisites that they may need to know before reading the content.
• Get answers for all the why questions. Instead of letting the user know technically what happens when they complete a task, like ‘Saves the details’, tell them in real world what would happen – ‘The page is saved now and you can access it any time later for reference.’

The third factor that impacts usefulness is lacking a structured approach to leveraging user feedback. Users give their feedback in multiple ways – support tickets and comments are a few to say. The most important feedback is silence. Yes, silence! In today’s competitive business world, silence or being indifferent is a larger threat than receiving negative feedback. From content perspective, if the users are indifferent to your content, it can mean the product is easy to understand, content is not useful, or the content is not findable when they need it and where they need it.

• Create a process for continuously receiving and reviewing user feedback from existing channels like support. This feedback need not be about content. Even an issue raised by user that require guidance from support team can be a reflection on content. Remember that any product content is useful when ‘needed’. Having the feedback loop gives you an insight into whether the content is useful and relevant and also whether the content is easily accessible when needed.
• Push your agenda. Make sure your customer-facing teams are aware that content comes with a cost and that it is important that even content receives continuous feedback from users. Sensitize the product management team and other field teams and make sure they gather feedback about documentation. This will ensure that you are on the right track and that there is positive ROI for your efforts.

Keep your customers at the center when you are taking content decisions to ensure you are producing content that makes sense to the customers. Optimize your tools and processes so it helps you spend your time on doing the right thing for the customer, that is, focus more on the content or the information you provide. Technically accurate and relevant content is far more important than the cosmetic changes that can take away our valuable time.

About the Author

Nivedita Aggarwal

Nivedita is Director, Information Services at CA Technologies. She leads APJ/EMEA
operations for CA Information Services and manages global tools, standards, and processes for
the same. She is also responsible for CA Globalization Services that include product and
documentation translation for all products at CA. With more than 16 years of work experience,
including 12 years at CA Technologies, Nivedita has a successful track record of leading a team of
90+ members across geographies including APJ, EMEA, and US. She has been a regular speaker at STC, Grace Hopper India Conference and Google Women TechMakers Summit. You can reach her at:

CA Email id: Nivedita.Aggarwal@ca.com
Personal email id: nivedita01@gmail.com