I've been doing open source documentation for a long time. Over the past decade, there have been a lot of attitude shifts regarding authoring and publishing. Some of these trends seem to go in cycles, such as the popularity of semantic markup. The latest trends move documentation closer to code, what many have called docs as code. Let's look at a few of the larger themes in documentation trends:
1. Git
When I first started doing documentation work for GNOME, we wrote our documentation in DocBook and stored it in CVS repositories alongside our code. These days, most GNOME documentation is written in Mallard and stored in a Git repository (after a brief stint with SVN). Although formats and tools have changed, the constant factor is that sources are stored in revision control, just like code.
It may seem odd to call this a trend when we've been doing it for so long, but a few things have changed, and some of that revolves around what Git has brought to the table. Git is one of the decentralized version control systems that arrived on the scene over the past decade or so. Some people continue to use decentralized version control systems the same way they used CVS or SVN, but that doesn't expose the real power of these systems. Documentation writers are increasingly proficient using Git for what it is. They're creating development, staging, and production branches, and they're merging disparate contributions. This wasn't as common just a few years ago.
Git is certainly not the only decentralized version control system. There are also Bazaar and Mercurial, to name just two, and you will find writers wielding the same power with those tools as well. But Git has taken the majority of the mind share, thanks in large part to popular Git hosting sites.
This is an area in which open source has lead the trend in the overall software documentation industry. A quick glance at technical writing forums will show plenty of people across the industry looking for information on how to effectively transition to Git. In the past, they may have stored their sources on a network drive with no revision control, or they may have used a proprietary management system. Git and tools like it have drastically changed the way the entire software industry deals with documentation.
2. Lightweight languages
There have always been plenty of choices for documentation source formats. There are semantic XML formats, and SGML formats before that. There are TeX dialects and troff dialects. There are the source formats of word processors, page layout tools, and help authoring tools. There are the internal formats of various wikis and content management systems. There's HTML. And there are a handful of lightweight markup languages that are designed to be easy to type in a text editor.
People are increasingly choosing lightweight markup languages for a number of reasons. They are usually easier to write, at least for simple things. They tend to play better with version control systems, because they're generally line oriented. And they can help lower the barrier to entry for new contributors, although you should be careful not to expect a change in source format alone to drive lots of contributors to your project.
Lightweight markup languages have their downsides, too. The tools for working with them tend to be limited in scope, and don't often provide the kind of data model you need to write other tools. They also don't usually provide as much semantic information. With XML formats, for example, there are a wealth of tools for translation, validation, link checking, status reporting, and various types of testing and data extraction. This kind of tooling isn't currently as extensive for lightweight formats. So although lightweight formats might ease the barrier to entry for new contributors, they can also create new barriers to long-term maintenance. As with all things, there are always trade-offs.
The three most popular lightweight formats right now are Markdown, AsciiDoc, and reStructured Text. Markdown is the simplest, but it doesn't offer much for anything but the most basic documentation needs. It also comes in many different, slightly incompatible flavors, depending on which processing tool you use. AsciiDoc offers more semantics and more types of elements. It originally focused on being a front-end to DocBook, but it has grown to natively support lots of output formats. reStructuredText came from the Python community, and for a long time its use was largely limited to Python projects. It has grown in popularity lately due to hosting sites, such as Read the Docs.
3. Static site generators
Five years ago, the trend was to use wikis and blogging platforms to create documentation sites. They were easy to set up, and giving people accounts to contribute was easy. Particularly brave people would even open their wiki to anonymous contributions. These days, the trend is to keep sources in version control, then build and publish sites with mostly static HTML files.
Generating static sites isn't new. My first job out of college was working on internal tools used at a software company to build and publish static files for tens of thousands of pages of documentation. But static sites have become increasingly popular for projects of all sizes, for a number of reasons.
First, there are increasingly good off-the-shelf static site generators. Tools like Middleman and Jekyll are just as easy to deploy as a wiki or a blog. Unless you have specialized needs, you no longer have to write and maintain your own site-generating tool. Static site generators have become increasingly popular among web developers, and technical writers get to ride that wave.
Another reason static sites are more popular is that source hosting sites are easier to use, and a growing number of technical people use them. One of the draws of a wiki was that somebody could contribute without downloading anything or installing special tools. If your source files are stored in a hosting service like GitHub, anybody with a GitHub account can edit them right in their web browser and ask you to merge their changes.
4. Continuous integration
Continuous integration is the key that ties the previous trends together. You can write your documentation in a simple format, store it in Git and edit it on the web using a Git hosting service, and publish a site from those sources. With continuous integration, you don't even need a human to kick off the publishing process. If you're brave, you can publish automatically after every commit to master, and you'll have a nearly wiki-like experience for writers.
Some projects will be more conservative and only publish from a production branch. But even when publishing from a branch, continuous integration removes tedious human intervention. You can also automatically publish staging sites for development branches.
Continuous integration isn't just about publishing, either. Projects can use it to automatically test their documentation for things like validity and link integrity, or to generate reports on status and coverage.
5. Hosted documentation services
Automatically publishing documentation sites with continuous integration is easier than ever, but now there are hosted services that take care of everything for you. Just pass them a Git repository, and they'll automatically build, publish, and host your documentation. The most well-known example is Read the Docs. Originally coming out of the Python community, its ease of use has made it popular for all sorts of projects.
Whether free hosted documentation sites can be financially viable remains to be seen—to keep sites like that running costs money and people hours. If the sites can't maintain a certain level of quality, people will take their documentation elsewhere. If you benefit from one of these free services, I encourage you to see how you can help financially.
I believe the hosted documentation services trend will continue. Smart people will figure out how to smooth the bumps. I also suspect we'll start seeing paid hosted documentation services for proprietary software. Open source has led the way on documentation technology over the past decade, and it will continue to do so.
Comments are closed.