Stay current with the latest in tech comm
Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

Stitcher radio

Search results

Upcoming event:
I'm giving an API documentation workshop in San Francisco, California, on November 19, 2019. Check it out on EventBrite and register today to receive a $100 early bird discount.

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

by Tom Johnson on May 15, 2019 • 0 Comments
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 Readthedocs.com or Readme.io.

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.io. 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.

follow us in feedly