Heroku is now sporting an updated docs layout at docs.heroku.com. These new docs should be much easier to navigate and link to.
We built this as a standalone Sinatra app serving Markdown files, partially inspired by Assaf Arkin’s approach to Buildr. This makes it as snappy as staticly rendered pages, while retaining the flexibility of a dynamic app on the backend.
The docs app is deployed as a regular app on Heroku (just like this blog). Nothing special-case here: we deploy with git push, just like any other Heroku user. Dogfooding is good for you.
The app’s source is on Github. Fork and send us a pull request if you want to make edits to improve the wording, fix a typo, or even add a whole new section. Watch the repo to keep an eye on new additions to the docs. Or fork and use the code as the basis for your own docs app (though we ask that you not use our images or colorscheme).
Let’s also take a moment to give a nod to AsciiDoc, which we’ve been using for our docs up until now. Although it didn’t turn out to be a long-term solution as a docs CMS, it was a great way to get off the ground. We highly recommend it to anyone looking for an easy way to get good-looking HTML docs generated from a simple and intuitive markdown format.