Docs Like Code: an Interview with Anne Gentle

A few weeks ago Kate and I had the great privilege to chat with the Anne Gentle about docs as code. While I endeavor to curate highlights from all of my videos, the primary purpose of this blog post is to

1. let you know that a video of this excellent conversation exists
2. convince you to watch the entire conversation (or read the transcript)

Why? Because everything Anne has to say is really, really good.

Still here?

Might I point out that the video is a quick 15 minutes and 33 seconds (because tech writers are that efficient), or under 8 minutes at 2x speed. Look, I will even just embed the video right here (instead of making you scroll to the end):

Still still here? OK, then, here is why you should watch the entire conversation.

We define docs as code

If you are a tech writer or documentarian, chances are that you have heard the term “docs as code”. However, as many non-documentarians may be unfamiliar with the term, Kate asked for a definition of docs as code aimed at a general audience, to which Anne replied:

Docs as code is basically taking developer techniques and applying them to documentation. So it’s using GitHub, the collaborative version control system, test automation. So running your docs through testing, through a device like a linter, which is a way to make clean code–you can also use it to make clean docs. And it’s that continuous integration, continuous deployment so that you have source for your docs, and then it’s also building something that can be published immediately.

As Anne notes, the developer techniques involved mean that docs as code is “for your techie tech writer,” but that also means that docs as code processes can be very developer friendly and also integrate nicely into existing CI/CD pipelines. And while it cannot guarantee that documentation will be kept up to date, it at least puts processes in place to better combat documentation neglect and sprawl.

Anne Gentle wrote the book on docs as code

Anne first published Docs Like Code: Write, review, test, merge, build, deploy, repeat in 2017 (and there is a companion website). “Docs like code” is simply another name for “docs as code”, although the latter adheres to the super-trendy practice of reframing all things as code. As Anne notes:

It’s the whole “something as code,” I think, movement is really where we’re going. Infrastructure as code, network as code, docs as code. It just makes a lot of sense. And I was just lucky to be there when we were really integrating with development teams. And it just made sense, right? It was Sphinx. It was RST — these tools that made a lot of sense…And you know, it’s basically working towards that collaboration aspect of documentation, especially with developers and docs for developers.

There is so much going on in just these few sentences. First, the alignment of docs like code/docs as code with the “as code” trend. Then the recognition that docs as code practices in part emerge from collaborative efforts among documentarians and developers, resulting in new processes for producing documentation. Also thrown into the mix: a shout out to documentation generators like Sphinx (which can ingest docs written in a markup language like RST and turn it into HTML)–one of the common components of docs as code setups.

I also want to point out how easily Anne brushes off her history with docs as code as a matter of being in the right place at the right time. Many of us lived through the emergence of docs as code but not all of us wrote a book about it (and then also wrote or contributed to a number of other technical books). As modest as Anne may be about her accomplishments, it is worth remembering, as one of the comments on our conversation’s YouTube page notes, “she is no less than a celebrity in the IT world.”

Docs as code is evolving

In late 2022 the third edition of Docs Like Code dropped with a new subtitle: Collaborate and Automate to Improve Technical Documentation. While the changes to the subtitle per se reveal a bit about the book’s evolution–it is more collaboration and automation forward–Kate and I also asked what the revision process was like. Collaboration came up yet again, as Anne was quick to credit fellow tech writer Diane Skwish:

So what I did for the revision process, Diane Skwish is here in Austin with me. She and I had both been at different companies with various docs as code techniques and different teams we had been working with. It was still pandemic time, but we could go to breakfast and just have really good conversations about what we’re observing. And so huge shout out to Diane. The next edition wouldn’t have even happened without her. But you know, I think we were both seeing these trends we wanted to get into the next edition.

Some of these trends reflect the maturity of docs as code as a concept, including a greater emphasis on governance: (“So what governance means is how do you take in changes? How much review do you need? How much planning ahead of time do you need for that?”) and the emergence of docs as code as a required skill in job descriptions. Other trends reflect broader changes in the world:

Obviously the world changed just a little bit in that time frame, right? So there were just a lot of things going on. 2020 Black Lives Matter movement: that meant a real push towards inclusive language. And guess what? Those linters are a really great tool to help with inclusive language, looking for biased words, looking for those terms, eliminating them, making sure they don’t come back in. And so I think that was just such a — yes, it was born out of real turmoil, but it also helps our industry move along towards more inclusive language. And we all believe words matter, of course–the docs are in! So I just think that was another piece of the world changing that we could move towards.

As late 2020 also saw the creation of the Inclusive Naming Initiative, this seems particularly on point.

Anne also talks about some of the improvements in tooling in the last five years (online editors in GitHub, anyone?), and then points to Goodreads as an excellent source of feedback that helped her shape the Docs Like Code revisions. One “good criticism” of the book that Anne acknowledges persists: while it can help you get started with docs as code, it is not meant as a general introduction to tech writing per se, so adjust your expectations accordingly.

Yes, we talk about AI

But to hear our take on what generative AI might mean for documentation and docs as code processes (and also get our thoughts on prompt engineering), you’re going to have to watch the entire video of the conversation or see the full transcript and related links.

Disclosure: Cisco, GitHub, and GitLab are RedMonk clients. The video discussed here was sponsored by Cisco (but this post was not sponsored by any entity).