Meet Viewdocs

Last week @progrium striked again with one more great example of how we should strive for keeping things simple. Five months after releasing Dokku which is a Docker powered mini-Heroku written in around 100 lines of Bash, he has just open sourced viewdocs:

As with Dokku, the project is pretty small and (as of this writing) converts ~200 lines of Golang code into a powerful tool for small to medium sized open source projects hosted on GitHub. Viewdocs combines the dynamics of Read the Docs and the simplicity of Gist.io by rendering Markdown on the fly from your repository’s docs directory as simple static pages. It even supports custom layouts and rendering specific git references (like a tag, branch or a specific commit). How cool is that? :)

Seriously, the project is so simple that when Jeff opened up the code, it didn’t have support for rendering specific git revisions and even with less than a month worth of Golang experience I was able to implement the code to support that.

Why not GitHub Pages / <static site generator of choice> / Wikis?

If you’ve never heard about GitHub Pages, they are “public webpages freely hosted and easily published through GitHub’s site” or with “plain old git push”. It differs from Viewdocs as it serves html files or jekyll sites available on the gh-pages branch of your project and it comes with an automatic page generator that takes in a README.md + Google Analytics tracking code and spits out a HTML page with some nice looking templates.

Although GH Pages have the automatic page generator, in my opinion they lack that awesome “live documentation” feeling as it requires human intervention in order to be updated, either in the form of a few clicks on the automatic generator or a:

git checkout gh-pages
...hack & commit...
git push
git checkout master

For bigger projects with lots of contributors, having a separate branch and ensuring it is always up to date might not be an issue but for smaller ones (where there are one or two main devs) there’s a huge chance they’ll end up forgetting to update the branch after a release. Apart from that, as @patcon pointed out on this vagrant-cachier issue, it’s harder to “enforce updated documentation as part of any Pull Request”.

An alternative to make docs more dynamic, you can use project’s Wiki so that users can easily contribute back in case they think things can be improved. The drawbacks of that are probably the same of using GitHub Pages as you are not only on a separate branch but also on a different repository.

The cool thing about Viewdocs is that documentation just get updated along with the the rest of the project’s sources right there from master. Because it supports git references, you’ll get tagged documentation like (ruby-doc) for free! For example, if your project goes through some drastic 2.0 changes that makes it incompatible with the previous 1.0 releases, you can just add a link to http://<user>.viewdocs.io/<project>~v1.0/ somewhere on the new docs so that users can read the docs of the version they are using. Oh, and because it works across forks, you can even preview Pull Requests changes by visiting http://<other user>.viewdocs.io/<your project>~<pr-branch> from anywhere, there’s no need to get into your laptop to run some commands or fire up a server in order to look at them.

Please don’t get me wrong, GitHub Pages and Middleman are a great fit if you are working on a static website of its own but IMHO Viewdocs is a better tool for maintaining / hosting open source project’s documentation (and it comes with a high level of “hackability” built in ;)

Viewdocs is a building block!

Would you imagine that we could have project’s analytics with a badge on project’s READMEs?

Imagine if you could drop in some JS into your custom layout that reads things from some other service using AJAX and somehow enhances the static docs with some additional behavior? I’m not sure what might come out of that but it looks promising.

For now I’ll just start by putting some fat READMEs on a diet :)