By Ben Mansheim
Imagine you are sitting at your desk, three months into a new technical documentation job. The software that your company produces is highly technical and bleeding edge; it’s created by geniuses and it’s marketed to geniuses. Until you joined, the developers wrote the hundreds of pages of existing documentation to the best of their non-native English ability. You know that the documentation is not of the highest quality—not from your expertise, but because your main customer wrote their own administration guide for your software from scratch and sent it to your company for consideration as a replacement for the official documentation—and it seems technically good but not professional enough.
In this situation you might feel overwhelmed, underqualified, lost, hopeless, and ready to quit.
Just then, the product manager comes into your office and says, “I have an idea. If we assign a couple of pages to each technical person in the company for them to review, they can send you all of those hundreds of style and technical comments to process the changes, get approvals, and implement the changes.” You think, “Do I get a last meal before this sentence is carried out?”
This story is not made up. In fact, it ended as a dream, not a nightmare. But how?
The Documentation Quality Challenge
We know that content is king, but if the content is filled with technical or writing style errors, then the king will quickly be dethroned. High-quality new content requires that the right information be delivered in the right way so that the reader understands it. These two criteria of technical accuracy and writing style are critical to success.
In the area of technical accuracy, subject matter experts (SMEs) tend to explain technical information in the way that is most comfortable for them. They might include technical terms that are unfamiliar to readers, details that are unnecessary for the task, and language styles that are not designed to be easily understood by most readers. The responsibility of the technical writer is to mitigate for these tendencies while staying true to the technical details required by the reader.
In the area of writing style, writers tend to focus more on the method of communication than the content that needs to be communicated. Writers might exclude necessary details, simplify terminology, or reconstruct content to match standard writing guidelines. While the writer has access to the source of the content and can revisit the writing style, SMEs are dependent on the writers to update content if there are any mistakes. This situation creates a delicate balancing act.
Traditional Document Change Management
In traditional documentation departments, the writers are not the owners of the information but they are the authority of content. The SMEs hold the knowledge and the writer needs to massage that knowledge into text so readers can understand it and accomplish their goals. The writer stores that text in a repository—that only the writer has access to—to prevent untracked changes from unauthorized writers. As a result, any changes to that text must be passed through the writer so the text can be published as official documentation.
In our story of mass document editing, the developers can write their comments in a Word document, in PDF comments, or via any other change-tracking method, then each change can be validated for style and accuracy before it is included in the official documentation. Not all of the comments will be complex, but those that are complex are most likely very important and require technical review from more than one SME. In addition, after the comment is approved, only the authorized writer can implement the change in the writing software. The writer has to get the approved version of the text after all of the revisions have been made and enter it into the software.
Traditional documentation methodologies cannot support the kinds of mass changes that the product manager in our story is asking for without high overhead and risk.
Open Source Document Change Management
Instead of using this traditional system, what if you could:
- Give everyone access to the source text with the ability to recommend changes directly in the source text;
- Manage discussion about the changes;
- Record approvals of the final changes;
- Merge the final changes into the official documentation at the press of a button; and
- Revert sets of related changes without risk to the rest of the content.
Wouldn’t that be great? Well, when I was in the situation described in our story, we did all of these.
At its core, open source means that a product ships with the code that was written to produce it. The ability to access this source code creates the potential for modification and repackaging that is governed by a variety of open source licenses. It also can allow people to contribute modifications back into the core project, so that everyone benefits from those modifications. A robust version control system adds the security that any changes that are made can be isolated for precise review and merged and unmerged without risking any other content in the system.
Whether your documentation is proprietary and needs to be kept under lock and key or it is non-proprietary and can be shared freely across the Internet, open source documentation allows many contributors to participate in the process of creating high-quality documentation.
Getting into the Open Source Details
Often the content source is kept away from the SMEs to protect the formatting of the content or to ensure that changes are controlled. Let’s look at an example of how this open source process works to see how this situation is handled.
In the company from the opening story, all of the content was written in Markdown format. There are many markup formats to choose from, but Markdown is a simple markup language that uses common symbols to designate the most used formatting elements. Most of the time, the formatting of a Markdown file is limited to line markers that indicate that a line is a heading, unordered list, or ordered list. These simple styles are processed commonly by a static site generator (SSG), such as Jekyll or Hugo, into HTML files. The static site generators convert the markers into specific numbers or indent levels based on pre-packaged rules and generate the required HTML accordingly. Because the formatting of the files is so basic, there is little risk that a change an SME makes will cause unexpected changes in the formatting of the output, and no proprietary editing software is required. In addition, many developers are familiar with markdown from their development experience.
To mitigate against the change management dangers of sharing source files, the company stored the source files in a GitHub repository. Again, there are many implementations of git source control, but GitHub is one of the most popular and familiar to developers. Anyone who wants to make a change to the source must copy the entire body of the source into a separate branch. Then they can make changes without impacting the authoritative version of the source files. During the course of editing, any set of changes is committed as a group, or commit, to the branch. When the editor is finished with the changes, the set of commits is proposed to be merged into the master copy of the source files as a pull request. Commonly, the editor or the owner of the repository invites experts to edit and approve the pull request. The set of changes can be discussed and edited until it is approved and merged into the master copy of the source files. In addition to the highly granular level of change tracking, any pull request or even individual commit can be reverted without impacting the rest of the source files.
With these strengths, the source files can be shared with many people and the changes can be managed with a high level of confidence that only approved changes have been merged into the source files.
Let the Wild Rumpus Begin!
To conclude our story, the product manager quickly assigned a few pages of the documentation to every employee in a technical role. The employees had a few days to review the content on those pages and to open pull requests to incorporate changes.
By the end of the review period, more than 40 pull requests were submitted for changes to the documentation. Most of the changes were simple spelling mistakes or other corrections that the reporters corrected themselves, and I had only to approve and merge. I sent the remaining pull requests to other resources for correction and approval. In just a few days, we made many technical and writing style corrections that significantly improved the quality of the documentation, and we did it by improving everyone’s ability to contribute and without taxing any individual resources.
In this scenario, we applied the open source process to use internal company resources to improve the documentation. If the technical content in the documentation can be made publicly available, the same process can be used to encourage people outside of the company to contribute to improving the quality of the documentation.
Open source documentation principles encourage the content source to be maintained in formats and systems that allow public or private contribution to the documentation with a high level of certainty that the content will not be harmed by those contributions. For organizations that can consider implementing these principles, you can open your documentation to more contributions and leverage them to make high-quality documentation.
For more information about open source documentation principles and practices: https://www.docslikecode.com/
BEN MANSHEIM (firstname.lastname@example.org) moved over 10 years ago from building networks to writing documentation about them and has never looked back. Currently he serves as the Documentation Specialist at Redis Labs and runs the Write the Docs meetup in the Tel Aviv area.