Wikis and Gitit

2012-05-31

If you’re looking for a way to get some community-driven documentation together, or if you just want a system for keeping your own notes organized and rendered nicely, you might consider creating a wiki.

Community-driven wikis can be useful when you’ve got a number of people who’d like an easy way to contribute some documentation, and who are willing to be flexible with regard to others editing their content.

Quickly, some benefits of wikis:

easy to contribute to (just login and click edit)
basic styling already set up for you
people are generally familiar with using them

Some drawbacks:

a wiki can quickly turn into a disorganized mess of miscellaneous unfocused trivia :)
can be difficult to work with others editing your writing
lots of spam if you don’t limit who can sign up and edit

If you’re looking to start a wiki and need to choose one, I recommend gitit. In no particular order, here are some reasons why:

easy to install. For example, on Debian-based OS’s: sudo apt-get install gitit
easy to run: you just run the gitit command and the wiki starts its own server and is running.
easy to configure (though, there’s not much to configure): just have it spit out its default config file template, and edit it as you please. Then run gitit using that config: gitit -f your-config.conf

In particular, it’s easy to set it up such that only those whom you want joining/editing can do so.
comes with good documentation
uses Pandoc’s Markdown for its markup format (and so, uses Pandoc under the hood for markup processing). To learn most of Markdown in a couple of minutes, see this quick markdown example.
wiki pages are stored as regular files: one file per wiki page. And “sub-pages” are stored as files in subdirectories. Lovely.
wiki pages are backed by git version control
easy to upload files to the wiki (and shows the user how to link to them after the upload)
LaTeX-formatted math displays correctly. So nice. :)
Since it’s powered by Pandoc, syntax highlighting for code blocks.
support for “categories” (you can assign zero or more categories to a given page, so the user can ask, “show me all pages in {category}”)
other features (listed at gitit.net): Atom feed (site-wide or for a particular page), caching.
looks nice right out of the box

If you decide that a wiki is what you want, definitely have a look at gitit.