Email Newsletter

Search results

Reader question: Recommended setup for docs-as-code tooling?

by Tom Johnson on May 15, 2019 •
categories: general

A reader asks for my recommended docs-as-code tooling setup. I said probably Hugo with Docsy and Netlify, or maybe a solution like or

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 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 and 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.”

Sponsored content

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, For a lengthy case study I wrote, see Case study: Switching tools to docs-as-code.

Buy me a coffeeBuy me a coffee
follow us in feedly

About Tom Johnson

Tom Johnson

I'm a technical writer / API doc specialist based in the Seattle area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out my API documentation if you're looking for more info about that. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. 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.