Publishing developer documentation
While searching for a nice and easy way to publish developer documentation and make it available to other folks I found several options, so I’m sharing them here in this short-but-informative post.
The main distinction between the options is that some are self-hosted and some are available as a service.
Self-hosted: #
Both tools use Markdown for writing and don’t require server-side processing except serving file resources (html/css/js). You write the documentation in Markdown, customize the templates, generate the pages and put them on a server. This means that the documentation can be hosted on pretty much everything, from GitHub Pages to Heroku and more. The only difference between these two is that Flatdoc is not generating the static pages - it’s loading the Markdown documents in the browser and renders them in place.
Hosted: #
- ReadMe: Homepage
- Read the Docs: Homepage / Documentation
ReadMe is the new kid on the block, it’s free plan is sufficient for a lot of use cases and looks good. On the other hand, Read the Docs is the most popular choice in the OpenSource community, has built in search functionality and other powerful features (check out the documentation).
Which to choose? Hosted or self hosted? #
That depends of many factors. Is there a server available to host the documentation? Will someone maintain it? Do you need the documentation on a local/internal network or will it be available to the Internet?
For example, Mozilla uses both, the documentation for localForage is built using Slate, and the documentation for Brick is hosted on ReadMe.
What about API documentation? #
There are two obvious choices: Swagger and API Blueprint. Swagger is very popular and can be used to generate the documentation from the actual code. The Swagger specification is language-agnostic and there’s support for dozens of programming languages and frameworks.