Can we start by agreeing that documentation is important, and that we would like better documentation? Good. That saves me from writing a three-paragraph rant about why you should care, and you get to keep the extra time reading it would have taken you.
To business! As a technical writer working in the enterprise software industry for nearly seven years, I've seen a tremendous shift in attitude toward technical documentation by software users, creators, and organizations. If earlier in my career I was taught to document as much as possible, nowadays it feels like people care much more about content quality than quantity.
Documentation, interrupted
Shortly after I joined Red Hat, we had nothing short of a revolution when organizational changes led to the content services teams being positioned alongside customer-facing roles such as technical support, account managers, and customer experience managers.
This meant that we needed to play some serious catch-up and examine eve-ry-thing we did, because we now play a critical role in the customer experience of our products. No longer tucked away behind our engineers, tech writers had a formal seat and a voice, and the responsibility to go with it.
We embarked on an intensive investigation into how we approach documentation, in which we concluded that the most important—albeit hard—questions when approaching content are:
- How can we create useful documentation that users will actually read?
- How can we seamlessly integrate content creation into our existing software delivery process?
- How can we engage our communities to contribute to documentation with the same passion as they contribute to the code?
Of course, nobody lives in a vacuum, and as I got involved with open source communities and started attending tech events, I've encountered companies and projects that express these questions or some variations of them, which shows a general trend that makes me a very happy docs lady. Exciting times!
In this three-part article series, I'm going to attempt to answer these questions with the cunning use of real-life examples of successful documentation solutions from the open source communities as well as from Red Hat's documentation teams.
In this first installment, I'll focus on the first question, which discusses the philosophy of documentation. Then, in later articles I'll look at the remaining questions that address the technology and community aspects of the docs evolution.
Content strategy, the new philosophy of technical documentation
Let's look at the first question: How can we create the right content, for the right users, and deliver it to them at the right place and at the right time?
If you are familiar with the concept of content strategy, you might be wondering what on earth it has to do with technical documentation. Isn't content strategy the stuff of Web design and copywriting? Well, not anymore. If we treat documentation as a standalone product or as a delivery requirement to our software, we must plan, create, deliver, and manage our content just like any other deliverable, and this means forethought.
At this point I'd like to give a shout-out to Rich Bowen, who kicked off the Doc Dish column here on Opensource.com with his article RTFM? How to write a manual worth reading. He touched on several key elements of such forethought, on which I'll expand in this article.
Ask first, write later
At its core, content strategy focuses entirely on the user of the content—the reader. When we approach documenting a certain feature, component, or use-case, we must understand our audience. In no attempt 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 to find out who I'm writing for. Am I writing for end-users, developers, business analysts, or system administrators? Are my users total beginners or ninja-nerds?
Being able to determine the personas of my readers (the GNOME Help landing page is great example) gives you a foundation on which to build content that will be useful to those users. You can now ask the rest of the questions with certain assumptions about what my readers already know, how they think, and which content is most likely to engage them.
What do my readers want to know?
This question can reveal not only the type of information the readers want, but which format I should use for delivery. For example, when I was faced with writing a deployment guide for JBoss Fuse on OpenShift Enterprise, I had to really focus on the minimal amount of content that would help new users get started without flooding them with information about all of the cool stuff that they can do with Fuse or OpenShift.
In contrast, if you're creating a command-line tool or library for developers, a complete reference for all the commands and options that the tool provides is the natural extension of the usage of the product. And yes, a manual page is probably the best way to deliver this type of content; nothing beats the joy of running man [COMMAND] and actually finding good option descriptions and examples.
When do my readers need this content?
This question is closely linked to the subsequent where question, and sometimes the answer can cover both questions, but when addressed independently, the answer can reveal at which point in the software usage or contribution my readers are likely to need the content that I'm writing.
This means that if you're creating content for a uber-ninja open source project like Arch Linux, you can guess that readers would have already tried to solve their problems or achieve their goals independently, so by the time they look for documentation they're not only frustrated, but already know what they're searching for. In this case, a Wiki site is a perfect way to allow powerful search functions without investing so much in pleasant browsing, because ain't nobody got time to browse here!
Bonus points: At this point, you also can start thinking how often you release and curate the content. Which information would my readers need to know immediately after a version release? When do we EOL (end of life) content from earlier software versions? And so on...
Where do my readers consume this content?
Remember the manual page I proposed in the what question? That's a good example of effective content placement, in this case right there in the terminal. Similarly, embedded or context-sensitive help can make or break the user experience when you deliver an IDE or desktop application. And the importance of a good README front-page for your GitHub-hosted project is pretty much a given.
API references can be auto-generated from your code easily with tools like Sphinx auto-doc and JavaDoc, just to name a few. Investing in human-readable code comments can help not only your users, but any developer who needs to to update the code six months from now (including the developer who wrote it, let's face it).
Also, error messages. Not something that happens to other people, informative and clear error messages can save the user a visit to the documentation library, so there's no reason not to treat them as a formal content type that delivers information to the users immediately when the problem occurs.
Why do my readers need this content?
This question is probably the trickiest of all, because it puts the purpose of your content under scrutiny with the WIIFM (what's in it for me) test: Why are you even writing this content? Which pain are you solving for your readers? Why would they care about what you're writing? Lots of hard questions to answer, I know.
If we go back to the question I asked you, the readers, in the beginning of the article—the one about whether you agree that documentation is important—I wouldn't have invested the time and effort to write this article if I (and the bright folks from Opensource.com) didn't think that it would be useful to you.
Keeping 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 rest assured that you're not alone in thinking this way, I will have tried to construct the article in the most effective way possible, and hope that I engage you enough to make it to the end.
Great theory! But what if...
True, the approach I just described might be miles apart from how your organization or community views and handles documentation. I won't presume to have all the answers; the best advice I can give is to start small and see how it goes.
So if your company employs several technical writing teams, run a POC (proof of concept) with one of them. Keep your colleagues updated with the 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's 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 some solid progress. We even have content strategists for our documentation, brave souls who act as product managers for documentation, and perform crucial analysis and triaging of content so that we can focus our efforts on content that people will actually read.
Of course, the philosophical change is only the beginning. In the next article, I'll attempt to tackle the technological aspect of successful documentation.
Spoiler: It involves DevOps. (cue ominous music)
Dish
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 open@opensource.com.
4 Comments