Anne Gentle: 'How do you keep your authors happy but also make sure your customer gets what they need?'
Anne Gentle has seen numerous changes in the documentation world since she wrote the first edition of “DOCS LIKE CODE.” She’s also made some observations about the things that don’t change.
How has docs as code changed since the first edition of the book?
A short bullet list of what has happened in five years:
There are many more docs contributing guides.
There are many more public examples as use cases to study.
GitHub has an improved web interface for making updates.
It’s easier to use Windows to work on docs-as-code.
GitHub uses main for the default branch instead of master.
GitHub has an easier file-based view for reviews.
GitHub pricing changed.
Read the Docs has grown a lot!
Linters and inclusive language checks are more prevalent.
What were the other projects using?
Sometimes it would be a wiki, sometimes it would be a video project…or maybe something like a CMS or…a pure metadata collection, or code examples.
Docs as Code seems to be the standard approach now.
In software for sure. In API documentation, definitely. Anywhere that there's a developer needed or a developer view needed, I think it has been become more of the default.
Are practices changing at all?
I think, people are really more sophisticated with the tooling around community contributions or GitHub itself has become more user-friendly. You know, you can actually make an edit in your web browser – you don't even have to pull it down. Because that was the hardest starting point if somebody didn't already have an idea of what a development environment was…Now that people can just contribute with a web browser, that makes a world of difference.
What’s new in the Third Edition of “DOCS LIKE CODE”?
I hadn't really ever talked about linters previously, and I feel like people really get those especially if you're already in a CI/CD pipeline. They're already linting their code, probably, so adding an inclusive language linter in there makes total sense.
I hope we're at…a point where the testing with an AI is going to make more inclusive language.
We are already using AI to edit…autocorrect is an AI. Chat GPT is just autocorrect on steroids for words and paragraphs and sentences, right? I think Grammarly has already made me a better writer. And I think tools like Acrolinx are just amazing natural language processors.
Do you address developers differently from writers when you’re trying to bring them into a Docs as Code universe?
The Write The Docs community, the Read the Docs community, that is a bunch of developers who really cared about documentation. The founders wanted to set up really good CI/CD for their docs. And Python, I think, is a really doc-friendly, doc-centric developer Community.
So, you know, developers take to it really well and actually prefer it. I've gone to, DevOps Days Austin and presented Docs as Code there, and they're all into it. If they had never heard of it before, they're very excited and they're just looking for the best practices: Do I put the docs with the source code, Do I put it into its own repo, What are the best static site generators?
But I think there’s the tools side and then there’s the people process. So if you really have a large community, there's a couple anti-behaviors. One would be start a big change but don't consult with any of the maintainers that they actually want it. So you could write a bunch and then not get your PR merged anyway, because it wasn't the direction they were thinking. So one of the best practices is open an issue. Hey, I'm thinking of doing this. What do y'all think?
You talk about your work at OpenStack docs in the book, and there’s a mention of some DocBook and other XML documentation (p. 29 in the second edition). Did you keep those docs around and have them maintained by technical writers?
That was more how we started out. But actually a couple years later, we moved all of the docs next to the code… You can do either model.…We took them into RST at that point.
At Rackspace, we had a tools team that had built this pretty sophisticated DocBook-plus-WADL implementation, so that’s why we were there. The original specification before openAPI specification, and before Swagger, was WADL.
The interesting thing was, I choose DocBook because Red Hat used it. It seemed like the best for a big open-source project. They all totally worked in DocBook – that was it right there. So just weighing it with like, well, who do I think will come help. Let's go with DocBook for now.
And then later you had more developers, which led to reStructuredText?
Yeah, we had more developer contributors, and that was awesome.
Do you have many cases where developers and technical writers collaborate, but with different markup and different editing tools? Or do you try to keep their toolchains the same?
I think the whole point of Docs as Code is to get developer tooling for writing. I talked to a tech writer once, that once they saw continuous integration (and) continuous deployment, they were like I won't ever be able to work another way again. This is the best way. Because you can write instead of build, build, build, you know?
At Cisco, I’m the Global Lead for Developer Experience, and I have tech writers, I have advocates, I have developer Community folks, and we enable 700 people at Cisco to work in our Docs as Code tool chain…I mean we're probably at like over 1,000 docs projects…And here's the thing…It could be a technical marketing person. It could be a product manager. It could be a tech writer. It could be an engineer. We see a lot. I mean 700 people.
Do you use the same tool set and the same markup language across all the projects?
Yeah, we use markdown, we try to stick with the GitHub-flavored markdown spec. And then openAPI is another format. They first started this continuous integration, Docs as Code project before I joined, so it's probably six or seven years old now, but they originally took in Markdown, XSMART, -- which was Cisco’s DITA, as I understand it – and HTML.
Would you say that you avoid DITA because you tend to work in organizations that need to get developers to contribute? If you worked with a lot of technical writers using DITA would you discourage it?
I don't even think we have teams that want XML or HTML.
Unless you're doing translations..DITA is more complicated than almost anyone needs.
You have tradeoffs in complexity for authors and output, so for specific requirements, you'd choose the right tool for the job. If you're going to make requirements and tools simpler for contributors, Markdown is the way to go since it doesn't require an XML editor/validator. As another example, if you're working with Python contributors, RST is the way to go.
Suppose you need DITA for requirements like translation. In that case, you should empower your contributors, whether tech writers or developers, with the tools and training they'd need to write with DITA in XML. I have yet to have a translation requirement at Cisco for developer docs, but for their large docs site, Cisco uses a specialization of DITA.
I love DITA for teaching topic typing. Telling contributors to write a concept, task, or reference helps many people understand technical writing better.
But for trying to get the most contributions from the most developer-y people just stick with markdown.
So what did I forget to ask you about?
I was reading a couple of your posts and I think something people could really use – and I might just post this – is a requirements template. I feel like people just choose Docs as Code because it's the latest thing, but you really have to go back and say well what do I need. Do I ever need PDF? Do I ever need the scenario of someone needs to read this on a plane or someone needs to read this in …an air-gapped situation?
How important are images, how important are tables? How important is localization?
if you need interactive docs it's a whole set of requirements, right? If you actually need code samples to work, that's a whole set of requirements.
So you kind of also have to do like: Critical, Nice to Have, Nice-But-Not-Required.
You’re suggesting a checklist that walks people through the important questions because most people won't think of all the requirements unless someone asks?
And you do it from an authoring standpoint and you also do it from a customer standpoint, right? So how do you keep your authors happy but also make sure your customer gets what they need.
Did you have examples of a requirements template that you could share?
A requirements doc example was in the Write the Docs newsletter (four years ago now, whoa):
Where to find out more about Anne Gentle:
docslikecode.com (Get a copy of her book or read her articles.)
Check out her recent interview on RedMonk