I hope that in this day and age we all agree that project documentation is a must and not just an afterthought. No? We should be. But in case you work at one of those places where documentation is frowned upon (“Why waste time writing documentation, when you can code. Right?”), just take my word for it. Investing in project documentation will help you great deal now and in the future. You don’t believe me? Check this out. Better?

Now that we cleared that out, there is a question of what to use for documentation. If you are a one-man-band, anything goes. You can use Word documents, Open office (or whatever flavour of free office tool is these days) document or plain text files. You could use pen and paper, but pen and paper have a bad habit of not being searchable by keywords. Personally, I would vote against any form of official document format, as that might make someone think documentation must be something great. And since we, developers, don’t like to write, we know we cannot write something great (right?) and end up not writing the documentation.

If you are not a one-man band, you are in a right pickle. Your documentation needs to be shared and preferably not locked by a developer that went on a 3 month sabbatical to the jungle. Enter wiki.

Why wiki?

Wikis are a known and easy way of sharing, contributing and searching data. They’ve been around for over 10 years and are here to stay. Wikis also have this unofficial feel to them, meaning contributors don’t have to worry about which of million of styles they will use and (magically) this makes developers write more. More content means more documentation and more documentation is good.

But wikis have this weird syntax…

That is true. Wikis have weird syntax that you will need to learn. Good thing about it is you will need to know how to format headings, links, bullet and numbered lists, bold and italic text and code snippets. It takes about 5 minutes to learn that. For everything else, you can always consort to wiki syntax documentation.

How do I start?

There are millions of questions going through your mind looking at empty wiki. How should I organize it? What should I put on it? Seriously, empty wiki is a horrifying thing to look at. And it should be. Empty wiki is usless.

I propose baby steps approach. Start with something small, then expand. Remember, until you have written something, you don’t have anything to organize. So, stop over-thinking and start writing.

What do I put in a wiki?

My advice. Everything. I stand to reason that abundance of information is way better than no information and no matter how insignificant you think something is, it may prove to be of great value to someone (and most likely you) in the future. It can be as simple as a FAQ entry or as complex as technical specifications of a new project. Imagine a wiki being that piece of scrap paper you use to put ideas on. Then put it in readable form and publish it.

But, I don’t like to write.

The beauty of wiki is that you don’t have to write a novel. Just put in enough information to still be helpful. Even stating that “there is a nasty hack at line 1234” is better than saying nothing. Sure, it doesn’t tell anyone why there is a hack, but at least it warns someone to be careful. Sure, we would all prefer it would actually say “there is a nasty hack at line 1234 that is needed because very fortnight, if temperatures drop below zero, this didn’t work”, but in the end, nothing stops you from fixing it.