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


Now read this

Cool demo projects from #SpringOne2GX 2014

Want to learn Spring by example? Use the source, Luke! This is a list of the coolest example/demo projects that can be found at the SpringOne2GX conference Github space. For each project there’s a related presentation as well. Rective... Continue →