The docs-like-code approach to documentation production

The docs-like-code approach attempts to bridge the gap between what is often seen as two distinct fields: engineering and writing. One is viewed as practical and technical, the other artistic and personable.

The appeal of docs-like-code

Documentation writers have long-suffered from the perception that their work (writing documentation either for users or to document software) is not of particular value when compared to other types of work. It’s the idea that the software code is the most important part of a project, and everything else is an expendable add-on.

Technical writing is also sometimes (unfairly) seen as dry and boring, the province of the socially-shunned nerd.

In contrast, the field of software development is currently viewed as fashionable and hip, associated with disruptive startups and billionaires like Mark Zuckerberg or Bill Gates. It also uses lots of buzzwords that jazz up what might be otherwise seen as dry, corporate work, like ‘agile’, ‘scrum’, and ‘sprint’.

What is docs-like-code

Docs-like-code is part of a wider zeitgeist of taking inspiration from the software development industry. It’s an attempt to make documentation workflows more integrated with the product and provide a new, appealing image for this job role.

Even though it’s a relatively new movement in the business world, it’s drawn from the open source community which has already been using this model for a long time.

Taking this approach means you publish your docs in as timely a manner as possible, while at the same time have a robust process for regular revisions. This ensures the standard of your docs remains high and the content relevant, using agile development and continuous iteration. You use software development tools like Github to store, manage and publish your code in a collaborative manner.

Some of the key features of a docs-like-code approach to documentation are:

• It’s collaborative and used by teams
• Uses version control tools like Git, Github or Bitbucket
• Keeps documentation code and programming code in the same place
• Uses plain text files like XML
• Is more automated in how the site is built
• Uses programming scripts to check for errors

Docs-like-code probably means something different for everyone, and there won’t be one-size-fits-all.

Let’s look at some of the benefits of taking this approach to your documentation.

The benefits of docs-like-code

Imagine a team of technical writers sitting around, writing their documentation in a program like Microsoft Word, checking and editing it with the human eye. This potentially takes a lot longer than the docs-like-code approach, and is more susceptible to human error.

Docs-like-code means to use all the efficiency of software development processes to reduce the time and cost it takes to produce your docs. It also encourages technical writers to be more integrated with the development team and for both teams to have ownership over and pride in their docs.

Having the developers write the first draft of your documentation can potentially speed up the writing process because it won’t require chasing them up at a later date (probably when they’ve largely forgotten why they did something).

It can also enable production teams to block new features on Github if they don’t have completed documentation, raising the status of documentation in your software project by a large margin.

Rackspace have blogged in great detail about taking the docs-like-code approach to also crowdsource collaborative documentation. This means that both Rackspace employees and users have contributed to their docs.  

Anne Gentle’s book

Anne Gentle has written a book, Docs like Code, that explores this approach in detail. Her aim is to challenge the artificial knowledge hierarchy that exists in high technology. That code is the most important part of the work, and everything else is lesser than the code.

Her approach also dispenses with the idea of a lone technical writer solely responsible for the docs, and promotes a collaborative approach.

In this approach, developers might write a first draft of your docs instead of the other way around. This is radical because documentation is often treated as an afterthought by developers, or they believe their code to be self-explanatory.

Although this is an ideal, it may take some convincing to get your developers to do this.

A technical writer called Zerok has been one of several to criticize Anne’s book for being too focused on her own experiences and tools, as well as impenetrable to newcomers, but she has undeniably made an important contribution to this field.

Drawbacks of docs-like-code

Tom Johnson has published an interesting article about how he found the docs-like-code approach too unwieldy for his team’s processes. Although docs-like-code is a very popular idea, he emphasizes how docs are not exactly like code.

For example, in the docs-like-code approach, you’re meant to keep your docs in the same repository as your programming code. However, software engineers release their code much less frequently than technical writers, and many code repositories are never deployed publicly.

Tom’s solution is to keep his documentation in a Git repository and to publish externally on GitHub, but he doesn’t integrate his docs with the code repository. Anything else, he says, would be overkill.

Too exuberant a passion for the docs-like-code approach might lead some technical writers to try to force their documentation workflows into a model where it doesn’t quite fit. It is true that writers are generally meant to focus on what they’re paid to do - write - rather than potentially waste time with complicated tools.

Tom also reminds us that documentation must be reviewed from the user’s perspective, and then be marked with comments, which is difficult to achieve when using Git as a tool.

Final remarks

Although much of the docs-like-code approach focuses on technical documentation in development, it can be applied other types of documentation as a workflow model.

The docs-like-code approach could benefit a number of documentation writers who work in an environment where it would be easy to implement. Ideally, you’d have support from the management team and cooperation from the developers.

In fact, it will probably only work if it’s directed by senior management, who can encourage everyone on the team to cooperate.

You should avoid enthusiastically adopting heavy-duty software engineering tools if they aren’t strictly necessary for your workflow.

If you want to get started with a docs-like-code approach, Anne recommends contributing to an open source project on Github.

KnowledgeOwl offers dedicated knowledge base software to help you write your best support documentation. Take us for a free spin today.