Reader question: Recommended setup for docs-as-code tooling?
A reader asks,
If I had to set up an infrastructure (Docs-as-Code, Git, Jekyll?. etc) is there a workflow or Udemy course you’d recommend?
I’m currently using Jekyll with GitHub Pages for this blog and my API doc site, and Jekyll for docs at work with developer.amazon.com/documentation but with a custom engineering build workflow.
Jekyll and GitHub Pages is about the easiest setup out there and works well for small sites. But I’d actually recommend going with Hugo right now, and probably Netlify. Hugo seems to be the trending static site generator these days, and many previous Jekyll sites have shifted over to Hugo. Docsy looks like a sweet Hugo documentation theme built by Google. The Hugo Learn theme also looks good.
Jekyll’s not bad by any means, but when your site starts growing into thousands of pages, build speed becomes a real issue, and you have to implement build shortcuts to reduce the time for local builds. I still love that GitHub Pages builds Jekyll natively, so there’s still an argument for that. And I love how easy it is to create custom scripts in Liquid (which Jekyll uses).
In my previous post about red flags, I mentioned that you should probably look for pre-built solutions when it comes to tools, since companies typically want you to focus on content more than tooling. If you use Docsy, you already have a starting point for your documentation theme, but you’ll probably still need to do a lot of figuring out.
Some easier options (which involve third-party hosting) might be Readthedocs.com and Readme.com. You won’t have as much control, but that also means less time spent with tool development. A lot of your decisions depend on whether you consider yourself a “tools person.”
For more reading on tools, see the section on Publishing API docs in my API documentation course. Specifically, for a more in-depth analysis to the question of tools, see Which tool to choose for API docs — my recommendations. You might want to deep dive into your requirements and such. (If you find that everyone expects PDF books and localization workflows, then you might want to reconsider your direction with static site generators.)
Re courses on Udemy for docs-as-code, sorry. I don’t believe there are many out there, as this space changes quickly. However, see Anne Gentle’s book, Docs like Code. She also has some case studies on her site, docslikecode.com. For a lengthy case study I wrote, see Case study: Switching tools to docs-as-code.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.