Modern Technical Writing: An Introduction to Software Documentation

by Andrew Etter

At a minimum, product documentation should answer the following questions: What is this product? Why would anyone want it? These two questions are incredibly challenging for the average technical writer, a group of people much more focused on how than what or why. I've struggled with them many times. But if you can't answer these questions, you need to go back to the research phase,

Marketing departments often use these documents to write their own, hyped-up copy for advertisements or blog posts, but your own appraisal of differences should use a more neutral tone. In six months, the features described in the change log will no longer be so novel, but they will still be online. Readers shouldn't have to parse a corny sales pitch about the incredible potential of a new feature in order to learn that push notifications arrived in version 1.8.2.

In the software industry, you often hear the questions, "What does good look like?" and "How do you measure success?" For a documentation website, any answer should include some mix of metrics, bug numbers6, reader feedback, alignment with corporate strategy (if applicable), and finally, personal intuition. If you have access to metrics from other teams, comparative analysis often yields the most valuable insights. How does the number of documentation bugs compare to the number of calls to customer support? Do the most-used features of the product correlate with the most-visited pages of the documentation?

Consider the following statements from two hypothetical technical writers: "In my professional opinion, the content is clear, concise, correct, and complete. The language is professional, conforms to our style guide, and projects a strong brand. Some of the tables were too wide for print, so we now enforce a two-column limit on all tables. Overall, I'm happy with the quality of the documentation." "The application logs show that the product only has 1,300 users, yet the documentation received 2,400 page views last month. In that same timespan, readers reported six inaccuracies, all of which I resolved within 72 hours. The five most popular search terms return the pages I would expect, and the design team recently helped me optimize the header margins for readability. Overall, I'm happy with the quality of the documentation." I sincerely hope that you find the second argument more compelling. In any field, opinions become more credible when you attach quantitative metrics to them. Documentation is no different.

Learn everything about a subject. Write down exactly what an audience needs to know and no more. Make the content beautiful, discoverable, scannable, and searchable. Consider everything a draft, and iterate relentlessly. Make contribution simple.