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.
