Anne Gentle’s Docs Like Code was first published in 2017; the third edition came out in December 2022. Anne (who is also Global Leader, Developer Experience at Cisco) joins Kelly and Kate to talk docs-as-code/docs-like-code processes, how the landscape has changed in the last five years, resources for getting started with docs like code, and what changes AI and large language models might bring for docs processes.

This was a RedMonk video, sponsored by Cisco. Disclosure: Cisco, GitHub, and Google Cloud are RedMonk clients.

Resources from Cisco:

• Discover the power of Docs Like Code by checking out Cisco’s GitHub Learning Lab at developer.cisco.com/learning.
• Visit docslikecode.com to explore tutorials and resources on implementing Docs Like Code techniques.
• Learn from the expert herself: get Anne Gentle’s book “Docs Like Code” and stay ahead in the technical writing world.
• Join the Cisco community at community.cisco.com to look for opportunities to participate in open-source projects or get ideas for docs-as-code projects.

Rather listen to this conversation as a podcast?

 

Transcript

Kelly Fitzpatrick: Hello, this is Kelly Fitzpatrick with RedMonk here with my excellent RedMonk colleague, Kate Holterhoff. We’re here with another episode of Docs are In, and this time we’re talking about docs like code. With us today is Anne Gentle, who is the author of the book Docs Like Code. Anne, thank you so much for speaking with us today. To start things off, can you tell us a little bit about who you are and what you do?

Anne Gentle: Sure. And thanks so much for the opportunity and thank you for buying my book. That is so great to see it in print. I love that. Thanks so much. So, yeah, great to be here, Kelly and Kate. I work at Cisco. I’m the global leader for developer experience. So we build a bridge between the product teams that are making the APIs and the developers who want to use them to make solutions, right? So that’s developer advocacy, that’s API documentation, it’s developer community. So all of that for that bridge building. And then we have our developer portal, developer.cisco.com. So that’s my current purview and it’s a lot of fun. I really have enjoyed moving from, you know, pure tech writing into developer experience. It’s been a great move. So yeah, that’s what I’m doing now. I had a lot of experience in Open Source in the past too, and so that’s kind of in my DNA for sure. And so that’s my background as well, API documentation in a community setting. And so that’s what was the genesis for Docs Like Code. I learned a lot there, especially with the community members working so hard on getting the system set up, getting the community around it. So yeah, that is my background and what I’m doing today.

Kate Holterhoff: All right. Well, thanks for that genesis. So, docs as code, docs like code: it’s a topic that we’ve mentioned before on the show, but it’s also a concept that might be unfamiliar to many non-documentarians. So as someone who has wrote the actual book on the subject, do you mind describing what docs like code means for just, you know, a general audience?

Anne: Oh for sure. So Docs as code is basically taking developer techniques and applying them to documentation, right? 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, right? So it’s all of those things and all the good parts that are really useful. Because there are a lot of technical authors already using GitHub in these systems and so you can get the reviews from them or have them write it and you review it. So it just works really well. 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. So yeah, if you haven’t heard of it, take a look at docslikecode.com, docsascode.com, either one. And you know, it’s basically working towards that collaboration aspect of documentation, especially with developers and docs for developers.

Kelly: And one thing I noticed — so I clearly have the second edition — is so the second edition came out in what, 2017…

Anne: Right!

Kelly: Yeah, five years ago, and had the subtitle: Write, review, test, merge, build, deploy and repeat. I had to actually write all that down because my brain wouldn’t remember it.

Anne: Right, right.

Kelly: Yeah. And the third edition came out at the end of 2022 with a new subtitle: Collaborate and Automate to Improve Technical Documentation, which I love that kind of evolution of what docs like code is about, right?

Anne: And I mean when you pick up a book, I thought it was much more descriptive.

Kelly: You know, I think it is and it’s — the way we’ve been talking about documentation as being this kind of collaboration and then the automation element. That’s something that we’ve heard more and more even just in the past couple of years. But having gone through that process of revising for Third Edition, looking back, how has docs like code or docs as code evolved in that time? And what was that revision process like?

Anne: Yeah, five years is a long time in tech especially, right? I mean it’s, you know, probably 35 years, I don’t know. Anyway, it’s —

Kelly: 500 years!

Anne: Probably, yeah. But I think what I noticed — So what I did for the revision process, Diane Skwish is here in Austin with me. And so she and I had both been at different companies with various docs as code techniques and different teams we had been working with. So, you know, 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. And so I think there’s a lot more examples to look at online and a lot more governance examples. 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? I think too, there are job descriptions now where people want docs as code, so that’s huge. If you can get a job in this, and it’s really, really interesting to you, what a great match. Right? So, what else I did is, I’m a big fan of Goodreads, the site where you can review books, right? I read everyone’s input on that site and responded to them and tried to incorporate it into the next edition. So I love that feedback. It’s so great that authors can get, you know, real input from readers and it’s immediate input.

Anne: So what else? I do think that the tooling has improved. You know, GitHub itself is way easier to use. You can actually edit online and I still remember being at Rackspace and we were like, Oh, should we just make an online editor so that people don’t have to use a command line? And now GitHub has it. Of course it was a natural evolution, right? So I do think it is just evolving in a way that makes it more accessible to more people. Now, a good criticism of the book is it is — you better know how to be a tech writer before you read it. I kind of make that assumption. So I want to be clear about that. It’s not for getting started in tech writing. There are excellent books out there already. I definitely say take a look at what is — to get you just going in the whole scene of tech writing. But yeah, there’s way more examples to look at. So I felt like I could get case studies more easily.

Anne: Big companies are doing this now, right? And I think, too, 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 like 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, you know, I just think that was another piece of the world changing that we could move towards. And the pandemic. Now I don’t think I had specific ideas around remote work, hybrid work. But obviously it shows up and I think docs as code lets you do that because it’s such a good collaboration tool with asynchronous communication and so on. So yeah, five years is a long time and there were just things to pick out, right? So when you revise, you have your list, but then you better get your priorities straight for what’s important.

Kate: So you’ve mentioned tools and books. Could you just give us some of your greatest hits in terms of resources for folks who are interested in getting started with docs like code?

Anne: Sure. So there is a tool called GitHub pages and you just go to pages.github.com. You can run through this very simple step by step tutorial and that’ll just let you work with the tools and get a feel for this idea of a static site generator. It just makes the pages and publishes automatically. If that doesn’t get you hooked, I don’t know what will. But anyway, super simple learning point that has immediate results, right? We have a GitHub learning lab on developer.cisco.com. It’s a very important piece of this technique, you know, learning git. It could be with GitLab, It could be with Bitbucket. I’ve mentioned GitHub a lot, but it doesn’t have to be that. But another thing that I often tell people — interns, co-ops — find a way to do the work or volunteer to do the work. So in my case, I actually volunteered in open source well before writing this book because they were doing the interesting things that I wanted to learn, right? And so that was — my first book was about using wikis and technical communication. So it’s not an easy route. And one of the things that I think Google has done a nice job of is the Season of Docs. So that’s structured program, very much helping match projects up with writers who want to learn, right? So that is an excellent way to get involved in open source. And I’m also a fan of volunteering within your company. There’s always bad documentation somewhere. And if you can just offer your help, find a team that’s willing to let you experiment a little bit. I think that’s just a great way to get started. So, you know, resources wise: find tutorials. Practice, practice, practice. It’s like playing a guitar. If you don’t do it every other day, your fingers are going to not remember. So that’s the important piece is just find the resources that work for you. But then also continue by doing some kind of real world projects and keep working.

Kelly: I love that. And that fits with folks that we’ve talked to on this show about different places that you can actually put these things into practice as opposed to just going to a tutorial. And if I recall, docslikecode.com actually has — the first thing it does is send you, I think, to GitHub to kind of get started. And I’ve recently sent folks who are like, how do I get started with all of this? You have those resources to look over. So thank you so much for for having them up there.

Anne: Yeah, and actually that was sort of meant to be a supplement to the book, right? Because the book is cemented in time. It’s a snapshot. So yeah, docslikecode.com/learn tutorials that help you, you know, figure out what repos am I going to use? to what is a static site generator and what do I need to look for? What about PDF? So all of those things are available in tutorial format.

Kelly: So one last question. In the news these days we hear all about artificial intelligence and especially large language models such as ChatGPT. To your mind, as someone who’s been thinking about this space for a while and from different kind of roles, how do you see something like ChatGPT affecting documentation and docs like code or docs as code practices in general?

Anne: Well, you know, it’s — I’ve played around with it a bit and it it really is like an autocorrect on steroids, right? It’s just figuring out what you probably are going to write next. And so for the actual writing portion, you could pretty much get a nice little site to play around with to practice docs as code. You know, pretty straightforward — might be a getting started guide on blah blah blah. Right. I’ve also played with it for code examples and code snippets. Wow. Talk about taking a lot of headache out of the actual writing process. Just those code examples are going to be just sheer gold for trying to get the small snippets that take time to write. But if an AI can write them, that’s awesome. You have to be able to judge them for yourself, test for yourself. You know, because docs as code is intended to be a technical technique, right? So it’s for your techie tech writer. But I do see AI as being such a great, maybe like a supportive tool, an enhancement tool, and then that kind of frees up your time for strategic planning, for getting to know more stakeholders for actually talking to customers. So I’m happy to kind of outsource some of some of that to an AI for sure.

Kelly: Yeah, absolutely. Any of the part of writing that I don’t like, like, yeah, AI could take a stab at that and then I’ll kind of go through it. And one of the things I’ve heard recently — and I did not come up with this, it was somewhere on the interwebs — is that editing is going to be a more important skill so editing and curation, even say, curation of code snippets that you can have brought to you from AI and then deciding, you know, is this something that is any good or not?

Anne: Right. I’ve heard of the new term prompt engineer too. So someone who’s really good at writing prompts is a good kind of space to get into. And honestly, I’m already using AI for editing because I love Grammarly, I love Acrolinx. Those are very huge natural language processors that are making my writing better. So guess I’m already enhancing it with AI. You know, it’s just this next step.

Kate: All right. And with the autocorrect on steroids, I think we’re about out of time here. So I want to thank. Anne for joining us today to discuss docs like code and the state of documentation more broadly. And with that, the docs are out.