In trying to get company documentation off google docs and people’s laptops and into a more useful format, I have been researching developer-friendly tools for business documentation. Requirements went something like:
– must handle words and documents
– should be available locally, bonus points for revision history
– must publish to the web, and ideally be editable there
– should accept content in markdown
– must have access control (which wiped out my original plan of using a static site generator)

While I worked on this, we were using the wiki feature in GitLab … which pretty much hit the nail on the head. Further investigation showed that the wiki feature in GitLab (and indeed in GitHub) is a ruby gem called Gollum.

In fact, the real Gollum is better than the versions in the GitLab/GitHub, with a few more features and of course if you are running your own copy, you can configure it yourself to generate navigation and other nice additions.

The installation instructions are straightforward: it’s basically a ruby gem. Once it’s installed, you can just run gollum from the directory with the markdown files in, and it will bring up a server for you to access (by default: http://localhost:4567).

The home page is called Home.markdown but Gollum will present you with an interface to create all the content. You can also click on “Pages” to see a list of all the pages, and also any nested directories, which is useful if you have a lot of content and/or you don’t want to manually create link to everything (navigation generation is available).

When you edit via the web interface, every save creates a commit. Similarly, if you’d rather work with the markdown in your local editor then you need to commit your changes before they are shown in the web interface, something that confused me for the first few minutes! All it means is that I squash commits before pushing quite often when I use gollum.

On both GitLab and GitHub, you can clone the wikis locally, and I find this a much easier way to work with content than using the online editors. I run gollum locally to check that everything looks correct before I push my changes back to the main repos and make the content visible – it’s a great tool and I’m most impressed that it supports other markups in addition to markdown itself. You can use various markdown flavours, but also textile, restructured text, mediawiki markup and asciidoc, among others. If you’re already using another markdown tool for something else, it’s likely that gollum can support that also and save you from having to keep a handle on multiple markdown formats!

I hadn’t even heard of Gollum although it turns out I was using it all along, and I think it’s an excellent tool; I’m also considering installing it standalone rather than using the versions that are in our source control tools as it does have more to offer than the features we’re currently using. I’m interested to hear your experiences with Gollum or other developer-friendly documentation tools, so please leave me a comment if you have something to share!