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:
Easy, elegant project documentation in Markdown using Viewdocs – Read the Docs meets Gist.io https://t.co/FIDrwPLgKc— Jeff Lindsay (@progrium) November 11, 2013
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
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
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.