Rethinking Documentation: Part 1, Content Strategy

Can we start by agreeing that documentation is important and that we would like better documentation? Good. It saves me from writing a three paragraph rant about why you should care, and you can keep reading for the extra time it would have taken you.

Business! As a technical writer working in the enterprise software industry for almost seven years, I have seen a dramatic change in attitude towards technical documentation among software users, developers and organizations. If earlier in my career I was taught to document as much as possible, nowadays it seems like people care a lot more about the quality of the content than the quantity.

Documentation, discontinued

Shortly after I arrived at Red Hat, we experienced a real revolution when organizational changes led the content services teams to position themselves alongside customer-centric roles such as technical support, account managers and managers. customer experience.

This meant that we had to seriously catch up and consider all we did because we now play a vital role in the customer experience of our products. No longer hidden behind our engineers, the technical writers had a formal seat and a voice, and the responsibility to accompany it.

We embarked on an in-depth investigation of how we approach documentation, in which we concluded that the most important, albeit difficult, questions when we approach content are:

  • How can we create useful documentation that users read?
  • How can we seamlessly integrate content creation into our existing software delivery process?
  • How can we engage our communities to contribute documentation with the same passion as they contribute to code?

Of course, no one lives in a vacuum, and as I got involved in open source communities and started attending tech events, I met companies and projects that expressed these questions or some of their variations, which shows a general tendency that makes me a very happy docs lady. Exciting moments!

In this three-part series of articles, I’ll attempt to answer these questions using real-life examples of successful documentation solutions from open source communities as well as Red Hat’s documentation teams.

In this first article, I will focus on the first question, which deals with the philosophy of documentation. Then, in later articles, I will examine the remaining questions that deal with the technological and community aspects of the evolution of documentation.

Content strategy, the new philosophy of technical documentation

Let’s take a look at the first question: How do we create the right content, for the right users, and deliver it to them in the right place at the right time?

If you are familiar with the concept of content strategy, you might be wondering what this has to do with technical documentation. Isn’t content strategy part of web design and copywriting? Well, not anymore. Whether we treat the documentation as a stand-alone product or as a delivery requirement in our software, we have to plan, create, deliver and manage our content like any other deliverable, and that means foresight.

At this point, I’d like to thank Rich Bowen, who started the Doc Dish column here on with his RTFM article? How to write a manual that is worth reading. He touched on several key elements of such foresight, which I will expand on in this article.

Ask first, write later

Basically, content strategy focuses entirely on the user of the content, the reader. When we approach the documentation of a certain feature, component, or use case, we need to understand our audience. Without wanting to be original or reinvent the wheel, I will use the famous five W’s to explain this thought process.

Who are my readers?

As Bowen pointed out, the first step in creating useful content is knowing who I’m writing for. Am I writing for end users, developers, business analysts, or system administrators? Are my users newbies or ninja nerds?

Being able to determine the personas of my readers (the GNOME Help landing page is a great example) gives you a foundation on which to create content that will be useful to these users. Now you can ask the rest of the questions with some assumptions about what my readers already know, how they think, and what content is most likely to engage them.

What do my readers want to know?

This question can reveal not only what kind of information readers want, but also what format I should use for delivery. For example, when I was faced with writing a deployment guide for JBoss Fuse on OpenShift Enterprise, I really had to focus on the minimum amount of content that would help new users get started without flooding them with information about all the cool things they can do with Fuse or OpenShift.

On the other hand, if you are creating a command line tool or a library for developers, a complete reference for all the commands and options provided by the tool is the natural extension of the use of the product. And yes, a man page is probably the best way to distribute this type of content; nothing beats the pleasure of running man [COMMAND] and find good descriptions and examples of options.

When do my readers need this content?

This question is closely linked to the or question, and sometimes the answer can cover both questions, but when treated independently, the answer can reveal at what point of software use or contribution my readers are likely to need the content that I write.

This means that if you are creating content for an open source uber-ninja project like Arch Linux, you can guess that readers would have tried to solve their problems or achieve their goals independently before, so by the time they search for documentation, they are not only frustrated, but already know what they are looking for. In this case, a Wiki site is a perfect way to enable powerful search functions without investing so much in pleasant navigation, because no one has time to navigate here!

Bonus points: At this point you can also start thinking about how often you post and organize the content. What information should my readers know immediately after posting a version? When do we edit EOL (end of life) content from previous versions of the software? Etc …

Where do my readers consume this content?

Remember the man page I suggested in the What question? This is a good example of efficient content placement, in this case in the terminal. Likewise, built-in or context-sensitive help can make or break the user experience when delivering an IDE or a desktop app. And the importance of a good README homepage for your GitHub hosted project is pretty much obvious.

API references can be automatically generated from your code easily with tools such as Self-doc Sphinx and JavaDoc, to name a few. Investing in human-readable code comments can help not only your users, but any developer who needs to update the code in six months (including the developer who wrote it, let’s face it).

Also, error messages. This is not something that happens to other people, informative and clear error messages can save the user a visit to the documentation library, so there is no reason not to deal with them. as a type of formal content that provides information to users immediately when the problem occurs.

Why do my readers need this content?

This question is probably the most tricky of all, as it puts the purpose of your content under control with the WIIFM (what’s in it for me) test: Why are you even writing this content? What pain are you solving for your readers? Why would they care what you write? Lots of hard questions to answer, I know.

If we go back to the question I asked you, readers, at the beginning of the article – whether you agree that documentation is important – I wouldn’t have invested the time and effort to write this article if I had (and the brilliant folks at didn’t think it would help you.

Bearing in mind that you are reading this article with the intention of learning how to improve your documentation, how to socialize the philosophical change in your organization, or even just to be sure that you are not alone in thinking this way , I will have tried to build the article in the most efficient way possible, and I hope I engage you enough to see it through.

Great theory! But if…

Granted, the approach I just described may be miles from how your organization or community sees and manages documentation. I will not claim to have all the answers; the best advice I can give is to start small and see how it goes.

So, if your business employs multiple technical writing teams, start a proof of concept (POC) with one of them. Keep your colleagues up to date on progress and document all your findings and processes for others to use if they choose to adopt this practice.

And if your open source project lacks technical writing experts, reach out to other communities for help. Collaboration is one of the pillars of open source software, and there is no reason not to pool our mental resources to create better documentation that everyone can benefit from.

Since we started this journey at Red Hat, we’ve come a long way in understanding our users and we’ve made solid progress. We even have content strategists for our docs, brave souls who act as product managers for docs, and do crucial content analysis and triage so we can focus our efforts on the content people are going. Actually read.

Of course, the philosophical change is just the start. In the next article, I will try to address the technological aspect of successful documentation.

Spoiler: This implies DevOps. (cue threatening music)


This article is part of the Doc Dish column coordinated by Rikki Endsley. To contribute to this column, submit your story idea or contact us at [email protected]

Sam D. Gomez