Choosing a Publishing Tool

Tools for publishing documentation are ones that make your materials publicly available in some fashion. In the modern documentation landscape, this almost always means tools that create websites, since that’s how software documentation is almost always delivered.

Taking an expansive view, there are many, many tools you could use to publish your documentation — essentially as many as there are different web hosting services. But there are a few crowd-favorite options that will meet the needs of the vast majority of projects. Unless you have very particular requirements, you probably only need to consider a few choices before finding one that will work for you.

ReadTheDocs

Most open-source Python projects publish their documentation using the ReadTheDocs.com service. ReadTheDocs has a free usage plan, supports any documentation tool (not just Python-based ones), and has good integration with continuous integration and deployment (CI/CD) services. This latter point is very valuable if, as recommended, you embrace the docs as code paradigm.

If you’re unsure whether ReadTheDocs would be a good fit for your project, consult its documentation to learn more.

Note that ReadTheDocs supports custom domains so that, with a relatively small amount of effort, your docs can be accessed via a branded URL like https://docs.mycoolproject.org/ even as they’re hosted by the third-party service. These days, most publishing tools offer this feature.

Additional Resources

“Pages” Services

Another extremely popular option is a static website deployment service integrated with your code host, such as GitHub Pages or GitLab Pages. While there are numerous general-purpose static website hosting services, these integrated options are likely to offer the easiest route to convenient docs-as-code CI/CD integration.

Broadly speaking, these services offer the same core features as ReadTheDocs: support for any choice of authoring tool (but possibly more convenient support for certain preferred tools); CI/CD integration; custom domains; and so on.

Additional Resources

Self-Hosting

We’ve highlighted the options above because they are very easy, very popular systems for publishing documentation. But if you’re unwilling or unable to rely on a third-party service to host your docs, it’s worth emphasizing that it is totally possible to host them yourself. Most authoring tools produce static web content as their output, and this is the easiest kind of content to self-host.

It’s beyond the scope of this resource to explore this topic in detail, but if you have access to local tech experts, they can almost surely help you out.