Which technical documentation standard is the "best?" This question is loaded with proverbial hills that technical writers will gladly die on. But you should think of it less like an entrenched battle and more like a quest to find what works for you and your organization. We’re going to explore each hill, see which to defend, and which hills are actually landfills in disguise.
It’s a tough question to ask, especially when technical writers carry valid reasons for their tools and practices of choice. It’s a fair question, though, that deserves more than a little deliberation because it ultimately permeates everything about our content, from the way we think about it, how we create it, and how we get it to our end users.
So, it’s less about the hills that each writer will vociferously defend, and more about surveying these standards side by side and letting fair analysis decide which standard truly is the best.
We’d love to just tell you “DITA rules” and be done with it, but that’s not how we critically examine anything. So we’ll show you everything we can and you’ll need to choose a hill yourself. Let’s chart the road we’ll take to scope out some hills.
There are plenty of angles to approach the guiding question of this article, but we first need to establish what standards are.
Standards: What Are Those?
Standards are guidelines your structured content must abide by.
A standard is a collection of rules that make structured content work. Your grasp of documentation standards is dependent upon your understanding of structured content, so if you’re unfamiliar, you can learn all about structured content in this video.
Standards are a common ground, a set of rules. In soccer, there are rules that keep players on the same page across the world. For instance, it’s a rule that you’re not allowed to touch the ball with your hands -- aside from throw-ins.
What would happen if you were playing a team that used different rules and picked up the ball mid-play and threw it down the field?
Yikes. That would be problematic.
The standard rules of soccer ensure that every team in the league plays with the same structure, the same rules of the game, therefore keeping everyone on the same page.
The same is true of structured content. When building structured content, it must follow the rules of a standard. Which standard is best for your organization is based wholly on your business needs.
The purpose of this guide is to help ease the research process and create a framework, so that you can identify the best standard for your documentation and overall business needs. To guide you through this process, we’ve put together a basic framework to keep us on the right track.
Creating the Framework
The best standard for documentation is the one that works.
But “works” is an ambiguous word. To help us figure out which standards “work” requires that we be more specific and consider each standard through a series of different criteria:
- Open Standard vs. Closed Standard
- History of Documentation Standards
- Capabilities
- Scalability
- Standards as an Organizational Reflection
After running the standards through these five criteria, you’ll leave with a better idea of which documentation standard might be best for your organization’s use case.
The standards we’ll examine are diverse and some you might not actually view as a standard necessarily:
- Markdown
- DocBook
- Microsoft Word
- Wiki
- Docs-As-Code
- DITA
Criteria 1: Open Standard or Closed Standard?
Each has its ups, downs, and in-the-middles, so we’ll compare and let you decide which path to pursue.
We’ll review a group of standards that are commonly used for documentation, but we’ll first explore the areas that all standards fall under: Open, Closed, and The Messy Middle.
Open Standards
An open standard isn’t owned by any single entity, business, or person.
At its core, an open standard is a collection of guidelines that keep technologies able to remain accessible to everyone. Open standards are community-oriented, available to everyone who wants access, and relatively transparent.
Open standards make sure that people play by the same rules within a free environment. Anyone can come to play, but there are some guidelines to make sure there’s an overarching semblance of order.
Closed Standards
A closed standard is a privately owned piece of software.
A much easier definition, closed standards are proprietary and controlled by an owning entity. For instance, when you buy a license for Microsoft Word, you’re unable to change how the software works because it’s owned by Microsoft.
You play by their rules because they own their rules and users can’t amend them. When they change their own rules, you’re required to abide by them. Period.
The “Messy Middle”
Okay, fine, we made this one up, but it’s important to talk about it.
The Messy Middle is a unique thing to talk about but common to experience. People like to talk about things in binary terms, so it only makes sense that we ignore the ambiguous overlap that pervades the middle of the techcomm spectrum.
Since I love LEGO® bricks, I’ll use them to illustrate an example. Typically, you can have as many sets as you want and all the bricks will fit with one another when mixed together.
Think of that as an open standard.
Now, imagine using pliers and superglue to change the LEGO® bricks to fit whatever purpose you had for them. They wouldn’t fit with the standardized, unaltered counterparts anymore.
This is the messy middle.
Organizations will often adopt an open standard and make alterations to suit their needs, and we encourage that! Tailoring an open standard to help your business is a smart use of shared information.
Where it can become problematic is when an open standard is altered so much that it evolves into something little different from a closed standard. Maintaining that balance is crucial to making the middle marvelous instead of messy.
Criteria 2: History
What are we dealing with and where do they come from?
Without knowing a little about a few of the more common documentation tools, it’s hardly possible to make a well-informed decision for yourself. There are six authoring standards that are most commonly used for technical documentation:
Now that you know what they are and where they came from, let’s see what they can actually do and what they bring to the table.
Criteria 3: Capabilities
Knowing what documentation standards can actually do is pivotal to them adequately serving your business needs. Evaluating the capabilities really comes down to asking "What have you got?" when faced with a big challenge like a fast approaching deadline, or a moody grizzly bear.
Markdown
Markdown is a lightweight markup language that is most commonly used in readme files that accompany software programs. It’s written in plain text format so that it can be easily rendered in HTML. Also, Markdown isn’t going anywhere. You can write Markdown in any plain text editor in existence.
Definitely the cool new kid in the documentation game, it’s all the rage in software documentation. It’s not hard to see why, either. It’s easy to learn, easier to use, and both of those things make developing documentation a pleasantly speedy process.
Between the ease of use and widespread popularity, Markdown is a great decision for documentation to a certain extent. It’s often used for technical documentation but lacks power in metadata, reuse, and version control that more robust standards have.
Still, if writing documentation for a smaller, single-purpose project, Markdown is ideal. We dive into more detail on the matter here: Markdown for Beginners: When Is It Most Appropriate?
DocBook
This is a semantic markup language based in XML. Content written in DocBook can be published to a plethora of different formats. DocBook takes a bunch of little pieces of data and turns them into reference files.
The structure of DocBook recreates the actual parts of a written book. The structural tags are named familiarly, with elements such as set, book, article, chapter, appendix, etc.
This whole book setup is nice for structuring content because pretty much everyone is familiar with the structure of a book. The inherent structure of the markup is intuitive, and it’s capable of publishing content to multiple different output formats.
Microsoft Word
You don’t need much introduction to Microsoft’s word-processing software. One of the most widely used programs for writing of all kinds, MS Word is commonly used for technical documentation.
The trouble is, MS Word isn’t a technical writing software, so its limitations lie within the fact that the closed standard wasn’t built for technical documentation in the first place.
Despite its design, MS Word remains one of the foremost word processing software programs for technical writing simply by default. It’s top of mind, easy to start using, and many company computers already have Word software included.
Wiki
Perhaps you’re familiar with the world’s largest wiki, Wikipedia? Then you’re familiar with how a wiki works. It’s an open-source platform that allows community contribution to the body of knowledge. Of course, as you may know already, one cannot simply submit anything they want. There’s a system of review that determines the validity of the content and deems whether or not it’s appropriate to publish.
Wikis are easy to learn and use. In the beginning, this may work for writing documentation. However, as your content matures, wikis can become unwieldy for managing larger bodies of content while ensuring quality and accuracy.
Check out our breakdown of when to use and when not to use wikis: Why Wikis Don't Work for Product Documentation
Docs-As-Code
Our little table earlier might not have been very helpful for this one, but there’s a reason for that/ Less a standard than a philosophy, documentation as code -- docs-as-code -- uses the same tools and methodologies for writing documentation as software engineers use for writing code.
For example, where developers write code in an IDE (Integrated Developer Environment), documentation would also be written in the same IDE. Where version control for code is managed with something like Git, documentation versioning would also be managed with Git.
Docs-as-code is a popular philosophy in the software engineering world. This is great when whoever is writing said documentation has a reasonably thorough background in the tools, methods, and processes of software engineers.
However, for most organizations, software engineers don’t write documentation and the people who do aren’t as readily able to adapt to those processes. The technical learning curve can be steep, though, once mastered, docs-as-code can be an effective documentation philosophy.
DITA
Darwin Information Typing Architecture -- DITA -- was created specifically for organizing technical documentation. It’s an open XML standard that we’re so familiar with, we built our software around it and talk about it with a reasonable amount of authority:
DITA uses content components to build documents piece-by-piece with written content completely separate from formatting. This allows documents to be constructed by modular pieces that can exist by themselves.
These modular content components can be reused as many times and in as many places as they’re needed. Then, when a component needs to be updated or edited, it needs only be done in one place and the changes will populate wherever the component is used.
Component reuse is one of the most powerful DITA capabilities, drastically removing the editorial hassle of tracking changes throughout a library of documents. Write once, publish everywhere. Edit once, update everywhere.
Criteria 4: Scalability
The growth of your company’s content library depends on your documentation standard’s ability to support it.
Markdown
Because it’s so fast and easy to learn/implement, Markdown is great for quick projects that don’t need constant documentation updates. As far as scalability goes, Markdown supports a level of metadata, though it lacks the semantic complexity to support documentation as it grows to enterprise scale.
Beyond metadata, large libraries of content scale to require several different output formats, which Markdown isn’t fit to handle.
DocBook
In some ways, DocBook is a great standard to use for scaling documentation. In terms of publishing output, DocBook keeps content separate from output styling until publishing. By doing this, writers don’t have to format for each document, rather, the styling is programmed and then automatically applied every time it’s published. This means that DocBook is capable of multi-channel publishing at scale.
One of DocBook’s common problems for scale is the reuse mechanism. While DocBook does have structured reuse (which puts them ahead of most of the competitors) that reuse mechanism is touchy because reused elements are not validated until the reuse step rather than when authored. This leads to scaling that falls on its face frequently.
Microsoft Word
Each document created in Word is its own document. Therefore, to scale an organization’s content, let’s use this example.
Say your organization has 1,000 different pieces of content written in Word Documents. If your company description was updated and needed to be changed in those pieces of content, your writing team would need to open 1,000 documents and make the same changes 1,000 times.
No.
In fact, we've put together a whole article of reasons that Microsoft Word doesn't cut it: 3 Reasons Microsoft Word Falls Short for Documentation
Wiki
Wikis are easy to contribute to, which makes scaling easy at first. Down the road, when the number of contributing authors grows and the library of content grows, keeping track of the updates becomes challenging.
It’s not so much the authoring part that’s a scaling challenge, but the content management piece. In a large content library, changes can slip through the cracks because there’s no consistent source of truth as a foundation for content management.
Consistency in content production is vital to scaling your content effectively. Even more important is your company's content credibility. Being poorly able to scale your content with company growth will take away from the authority you want your organization's content to confidently wield. Wikis lack sufficient power to maintain that support.
Docs-As-Code
As far as scalability goes, docs-as-code isn’t a bad idea. Because of its relationship with the coding side of things, docs-as-code is meant to operate more-or-less in tandem with software development, using the same tools, methods, testing, and timelines.
This, of course, demands that your engineering and documentation teams literal BFFs and work well together. The scalability of docs-as-code is largely dependent on organizational dynamics and your tech stack.
Docs-as-code lends itself to being advantageous to smaller teams who have smaller content sets, have minimal reuse and metadata requirements, need no translation, etc. If your content library and publication needs are more complex than that, you’ll need something more robust.
Still, docs-as-code can effectively be used alongside another standard designed for bulkier content sets.
DITA
The powerhouse of scalability with a steep learning curve. Don't let the learning curve dissuade you, though, because the benefits far outweigh the initial cognitive investment.
With rich, semantic metadata, content is easy to find. Component reuse makes it a breeze to use content in more than one place without bothering with copy-pasting. The same is true when content components need to be edited and updated. As said earlier, edit in one place, update everywhere.
DITA is a multi-channel publishing master. Because written content is separate from formatting, content is written can then be published to whatever outputs your organization calls for.
Again, it’s no secret that learning DITA can be intimidating at first, which is why the initial investment in learning and training will support an organization’s ability to more effectively use all of DITA’s capabilities down the road.
Criteria 5: Your Standards Are a Reflection of Your Organization
Returning to our earlier analogy, the defense of a hill isn’t just about keeping a piece of land, it’s also about defending and preserving what that hill says about us.
In many ways, the standard an organization chooses for its documentation determines priorities, value hierarchies, and indispensable capabilities.
This is a less granular question than it is a guiding philosophy. Because a documentation standard will be the foundation of your content and information architecture, it’s important to look critically at the big picture.
How will a certain standard help you right now? Is the solution sustainable for your organization as your teams and content repositories inevitably grow? How do you want your organization to shine through your content?
There’s No Magical Documentation Standard
Hate to say it, but there’s no one-size-fits-all answer. Despite the mythical flair of this post, there's no magic. The benefits of any standard depend wholly on what you’re using them for.
We use that phrase a lot, but you know that this industry has no universally perfect solutions. That’s why standards have grown with an ever-changing technological landscape.
What we can say is that there are good and bad solutions to specific problems. But, you have to identify those problems, determine the capabilities you need to conquer them, and weigh potential solutions with your organization’s operational goals in mind.
When choosing a hill to defend, you’re ultimately in charge of the choice. All I can do is show you an honest view of what some of the hills look like.
The standard you choose reflects your organization and ultimately encompasses your content library, so invest time and energy. Be selective and critically minded because your content is the voice of your product; there’s no sense in rushing that voice to speak before it’s ready.
