I described a smattering of tools in Docs-as-code tool options for developer docs. Which solution should you choose? It’s a complicated decision that will invariably involve tradeoffs. As I said earlier, the decision depends on your skillset, product, environment, and requirements. But here’s my recommendation. First, identify what authoring requirements you have. Then decide on a static site generator, and then consider a host and deployment platform.
The first step to selecting a tool is to define your authoring requirements. Start by answering the following questions:
Now that you’ve gathered some data about requirements, understand that you’re probably not going to find a single system that does all of what you need. There are tradeoffs with every tool choice. The question is which features you want to prioritize.
Maybe it’s more important to minimize the custom coding of a theme than it is to have complete control and flexibility over the solution. Or perhaps a modern web output is more important than the ability to render PDFs. Or perhaps you must have authentication for your docs, but you also don’t have a budget. These are going to be some hard decisions to make.
Also note that I don’t have total familiarity with all of these tools and solutions. My core experience is with Jekyll, GitHub Pages, and internally developed publishing pipelines. I have only dabbled or experimented with a lot of these other tools and platforms, so I can’t speak authoritatively about them.
If you want power and control to create the complex features you need (maybe you want to build a custom theme or build your doc site with unique branding), then use a static site generator such as Hugo, Sphinx, or Jekyll. If you have serious doc needs (or maybe you migrated from the world of DITA and are used to more robust tooling?), you’re going to want a platform that can go as deep as you want to take it. Jekyll, Sphinx, and Hugo offer this depth in the platform.
Granted, this power and control will require a more complex platform and learning curve, but you can start out easy with a ready-made theme and later work your way into custom development as desired.
If you don’t have web development skills and don’t want to tinker with theme or other code development, choose a static CMS solution such as Readme or Netlify CMS (though, with Netlify CMS, you’d still have to select a template). Readme provides a ready-made design for your API doc site, removing the need for both designing a theme and figuring out hosting/deployment. That can save you a lot of time and effort.
Realize that when implementing a solution, you might spend a quarter of your time over a period of months customizing your theme and working on other doc tooling needs. If you don’t want to devote that much time to your tooling, Readme is a good option. However, I personally want more control and flexibility over the information design and theme. I like to experiment, and I want the power to code whatever feature I want, such as an embedded navigation map, a special TOC for series items, or whatever. I think many developers want similar flexibility and control.
Additionally, if you have a large number of contributing authors who will need direct access to the system, consider whether you have the budget for a static CMS solution such as Readme.
If you want to use a static site generator, which should you choose — Jekyll, Hugo, Sphinx, or some other? Sphinx has the most documentation-oriented features, such as search, PDF, cross-reference linking, and semantic markup. If those features are extremely important, consider Sphinx.
However, choosing Jekyll or Hugo rather than Sphinx does have a strong argument because their communities extend beyond documentation groups. Sphinx was designed as a documentation platform, so its audience tends to be more niche. Documentation tools almost never have the community size that more general web development tools have. So the tradeoff with Jekyll or Hugo is that although they lack some better documentation features (cross-references, search, PDF, semantic markup), they might have more community and momentum in the long-term.
Markup is also a consideration. If you’ve narrowed the choice down to Sphinx with reStructuredText or Jekyll/Hugo with Markdown, then one question to ask is whether engineers at your company will write in reStructuredText. If they’ll write in reStructuredText, great, Sphinx is probably superior for documentation projects due to the semantic advantages of reStructuredText. But if engineers prefer Markdown, then maybe Jekyll or Hugo will be a better choice. (You can use Markdown with Sphinx, but when you do, some other Sphinx features become limited.)
If deciding between Jekyll and Hugo, consider your project size. Do you have thousands of pages, all in the same project? Will each author be building the project locally? If so, how much does speed (how fast the project compiles the output) matter? If speed is an important consideration, Hugo will probably be better. But if you prefer a larger community and a platform that integrates tightly with GitHub, or if your doc project isn’t gargantuan, then Jekyll might be better.
After you’ve narrowed down which static site generator you want to use, next think about hosting and deployment options. If you’ve decided on Sphinx, consider using Read the Docs. If you’ve decided on Jekyll, then explore GitHub Pages, CloudCannon, Netlify, or Aerobatic. If you’ve decided on Hugo, then explore Netlify or Aerobatic.
By using one of these platforms, you offload a tremendous burden in maintaining a server and deploying your site. Usually, within a company, engineering groups manage and control the server infrastructure. Setting up and maintaining your own server for documentation using internal resources only can be a huge expense and headache. It can take months (if not years) to get engineering to give you space on a server, and even if they do, it likely will not provide half of the features you need (like continuous delivery and a CLI). That’s why I recommend these third-party hosting and deployment options if at all possible.
Maintaining your own server is not the business you want to be in, and these third-party platforms enable you to be much more efficient. Removing the hassle of publishing through continuous delivery from the server will simplify your life unimaginable ways.
If you don’t have budget for a third-party host and deployment option, nor do you have internal engineering resources, consider deploying to an AWS S3 bucket. Jekyll has a plugin called S3_website that easily deploys to S3. It’s not a continuous delivery model, but neither does it involve uploading your entire site output every time you want to publish. The S3_website plugin looks at what changed in your output and then synchronizes those changes with the files on S3. It’s an inexpensive solution that works well.
If your company prefers to build its own publishing pipeline, before you go down this road, find out what features the internal solution will provide. Explore some of the benefits of these third-party host and deployment options and examine whether the internal solution will have enough parity and long-term support. If you have strong engineering backing, then great, you’re probably in a good spot. But if engineers will barely give you the time of day, I’d strongly consider a third-party solution. See Case study: Switching tools to docs-as-code for my experience going down this route.
At this point in the course, I haven’t yet explored the OpenAPI specification, but it could be an important factor in your consideration of tools. How will you display all the endpoint reference documentation? Rather than creating your own template or manually defining these reference sections, I recommend using a tool that can read and parse the OpenAPI for your reference documentation. Not many doc tools easily incorporate and display the OpenAPI specification (yet), so perhaps the best alternative might be to embed Swagger UI (assuming more deep integration isn’t possible) into your doc platform.
I’ve seen some deeper integrations of Swagger UI into existing websites, and some day I hope to do this with a Jekyll theme, but I haven’t yet. You could also create a theme based on Swagger UI itself using static site generator tooling.
Although this section has focused heavily on tools, I want to emphasize that content always trumps tooling. The content should be your primary focus, not the tools you use to publish the content. After you get the tooling infrastructure in place, it should mostly take a back seat to the daily tasks of content development.
In some ways, tools are the basketball player’s shoes. They matter, for sure. But Michael Jordan wasn’t a great basketball player because he wore Nike’s, nor was Kobe Bryant great due to his Adidas shoes. You can probably write incredible documentation despite your tooling and platform. Don’t let tooling derail your focus on what really matters in your role: the content.
I’ve changed my doc platforms numerous times, and rarely does anyone seem to care or notice. As long as it looks decent, most project managers and users will focus on the content much more than the design or platform. In some ways, the design should be invisible and unobtrusive, not foregrounding the focus on the content. The user shouldn’t be distracted by the tooling.
For the most part, users and reviewers won’t even notice all the effort behind the tools. Even when you’ve managed to single source content, loop through a custom collection, incorporate language switchers to jump from platform to platform, etc., the feedback you’ll get is “There’s a typo here.”
47/91 pages complete. Only 44 more pages to go...
If you would like to contribute back and encourage more available content and resources, you can click the Donate button below and contribute any amount.
Get new posts delivered straight to your inbox.
© 2017, Tom Johnson