Thursday, December 22, 2011

Developer Documentation


We used to store all of our documentation on one wiki but soon realized that we were serving two different audiences: end users and developers. We discovered a nice wiki feature in BitBucket and we now separate end user and developer documentation between Mindtouch and BitBucket respectively.

BitBucket also has convenient REST APIs that make it easy to integrate command line scripts with their source repository, issue tracker and wiki.

BitBucket Wiki

The BitBucket wiki uses the Creole syntax. It is a convenient place to store documentation for source code. I was not aware that it's possible to nest Mercurial repositories. Nesting allows us to conveniently layout our projects as follows (assume our project is called myproj):

$ hg clone https://bitbucket.org/alice/myproj
$ cd myproj
$ hg clone https://bitbucket.org/alice/myproj/wiki

This produces an independent wiki Mercurial repository at the root of myproj. You can now edit these files without switching to your browser.

BitBucket Issue Tracker

Although it's not as sophisticated as Bugzilla, the issue tracker in BitBucket is sufficient for small teams. And the REST APIs make automation relatively easy.



No comments: