Red Hat's product documentation is changing

Once upon a time, the term “product documentation” conjured images of ring-bound tomes several thousand pages long that would get shipped to users alongside the latest offering. In the days before the internet, this wasn’t just the best option available; it was the only option. It was big, it was slow, and it was expensive, but hey, what were you going to do?

When the internet came along, product documentation moved along with it. Installation guides, administration guides, and user guides jumped from CDs, to flash disks, to public websites, and users started turning to search engines for answers instead of the index page. Apart from where you’d find it, however, the format changed little from its previous appearance. These were guides, and guides they would remain.

My, how things have changed.

Gone are the days when users expect to sift through a giant manual and search for the information they need, piecing together the clues in the dark. Today’s users are search savvy and time poor, and they need the answers to their questions in one place, in one go. It’s time to shake off the shackles of tables of contents and navigation and reduce the number of steps between the reader and the answers they seek.

That is the central challenge that has driven Red Hat’s Customer Content Services team to revolutionize the way it develops and presents its product documentation. Stepping away from the traditional, monolithic view of content in guides, Red Hat started a program to re-imagine and reinvent the documentation experience from tip to toe, all based on the principles of modular documentation.

Modular what?

Everything we read today—from books and articles to blog posts and even social media updates—follows a set structure that sends cues to the reader about what to expect. Books are read from cover to cover, articles in a matter of minutes, and that tweet—just give it to me now so I can move on.

That’s a content model.

The traditional content model for product documentation collected content on similar topics into a single reference manual that users could search through to find all the information they needed. Information about virtual disks was found under a chapter on storage, network interfaces under a chapter on networking, and an installation guide would provide every option under the sun.

Slow, but broad.

In a modular content model, content is organized into three main content types—concepts, procedures, and references—that can be pulled apart and stuck together in any number of configurations based on what the circumstances demand. Not only does this make it more flexible, it means each unit can answer a single, fully formed question for the reader to take away when they’re done.

So what?

While the traditional content model provided a great volume of information, context is key. Rather than sifting through volumes of information to find the information they need, today’s users want to jump in at the right place, find the procedure they need, and get back to work.

In other words, fast and specific.

For the past few years, Red Hat’s Customer Content Services team has been working on a new way of developing and publishing documentation to do just that. As this work continues, our content has been shifting from monolithic titles of yore to more targeted content that answers individual questions and use cases. This means that the documentation can get out of the way and you can get back to the important part of the day—everything else.

When’s it coming?

Surprise, surprise—the modular revolution is already here!

With the release of Red Hat Enterprise Linux (RHEL) 8.3, we are pleased to announce the first release of content for RHEL 8.3 documentation in this new, modular format on the Red Hat Customer Portal.

A select number of guides are available in this format today, but there are more titles waiting in the wings as our system comes along.

The path to the future is modular, but that doesn’t mean we’re done. What you see today is very much in pilot form, with the main building blocks in place but many more features and finishing touches to come. For example, our print-to-PDF functionality today directs users to their native browser functionality to print a cleaner version of the page, whereas we plan to implement a more direct mechanism in the future. As such, there’s still plenty of development and preparation to go, but you can expect to see new features and documentation in this format become available over the coming year.

None of our content would mean anything without you, the customer. We are, first and foremost, here to solve the questions you raise, and we’d love to hear how we can continue to improve on this experience. Switch between the two experiences, have a read, and join the conversation using the feedback form available from the documentation page.