The work that developers put into applications can seem like dark sorcery to an outsider, making solid documentation crucial for users and other team members. Understanding the requirements, parameters, and scope of enterprise software is not always intuitive. Just as many teachers require students to show their work when solving problems, consistent docs are vital for helping a third-party grasp how they can get most out of the apps they use.

Robert Kratky, principal technical writer for Red Hat, will speak at Interop19 in May to discuss documentation and DevOps. InformationWeek caught up with him in advance of the conference to talk about some of the needs that drive documentation and how to get teams onboard with writing comprehensive docs.

What role does documentation play in the DevOps cycle?

"At Red Hat, documentation is quite important. Within Red Hat, the documentation department is part of the customer experience branch. Documentation consistently comes up as one of the major deciding factors for our customers who use our product. We try to improve upon it as much as we can. It is our way of contributing back to the open source realm as well as being selfish because the better the documentation that you write, the fewer customer tickets we tend to receive. We get a lot of encouragement from the support teams.

Historically, documentation has been a difficult pain point for software. Not that many programmers are keen on writing documentation. Documentation, at various points in time, has been thought of as a bit of an afterthought. It was important to get the features working to get the code out there, but the documentation was not necessarily the main priority. This is changing. People are very interested in documentation. It’s not that they would only read it when they are at a loss. They are using documentation as a deciding factor. We’re trying to accommodate that as much as we can."

How has your organization benefited from treating doc creation like coding?

"We’ve identified several areas of improvement that we can focus on. One of these things has been helped by the not-so-recent development in the DevOps area. The streamlining and joining of development and operations has given us a lot of ideas. We have come to find out that if we apply the same principles to documentation, we can save a lot of resources, deliver a better product, and better integrate with product teams within the company. It becomes more of a joint effort.

The main points of the new initiatives we are focusing on — we are consolidating the tooling that we use and make it more accessible for the engineering teams. The resulting expertise and knowledge are not riddled with gaps, and we can easily accommodate transitions between teams."

How does that change the dynamics within the organization?

"Different departments and teams have better visibility into how the processes in other departments work. This includes issue tracking, version control, and testing. A big part of that is automation, which in the case of code would be testing for validity and deployment. In documentation, they are also implementing automated tests that check for spelling, evaluate the quality of the writing, check for metadata so we know the document is being published correctly with regards to types of software that is related to or versions of software it pertains to. All this allows us to tightly integrate the engineering and support teams.

Mainly it results in improved customer experience. This automated testing, continuous integration, and deployment results in better quality of documentation. We try to eliminate human error and we have shorter reaction times."

Robert Kratky, Red Hat

Where does the discussion start within an organization about documentation?

"It relates to what documentation needs to be written. It is one of the most basic talks and one of the most important ones. The actual writing of the documentation, the manual work, it only comes after we determine what the users really need. What type of documentation is required for the product to be successful? This is a process that involves many stakeholders and it cannot only be entrusted to the documentation team. We seek input from many different areas.

First and foremost, it is the customer-facing teams who directly work with the customers. The support teams come into play when the customer has a problem. The field teams of consultants and solution architects work directly with customers implementing different solutions. We seek their input and they have very valuable feedback regarding how the documentation should appear and be written. They also have advice on how we can improve the processes. There are also product management teams that also take care of the actual presentation of the documents while we take care of the creation of the docs and make sure they are technically correct.

All this ties together into how we set up the processes and workflows so that the teams have visibility into it."

What are some historic pain points that current documentation tries to address?

"The criteria for the quality of documentation has ever been completeness. It was supposed to be fully featured and describe everything there was about a product. While there is inherently nothing wrong with that approach, it does not satisfy the user requirement where people need to solve specific problems. They need to get from A to B and are not that interested in the innerworkings of specific software.

Influenced by the agile development methodology, we are focusing on specific user stories so we can better identify what it is that users need from the documentation. It has transitioned from a self-serving documentation of every little nook and cranny of the software towards documenting what the users are really interested in."

 Red Hat's Robert Kratky will be presenting his session, DevOps Meets Docs: Documentation as Code, on May 22 at Interop.