Call me weird, but I like documentation. Like everything I do, I try to make the most of it and insert amusement into it as much as I can. You might remember the lessons I have learned when writing e-mail and if you do, good work. If you don't, you can go read that. This post isn't about e-mail, it's about the longer-lasting documentation that should live longer than your attention span and even your own fleshy memory.

It goes without saying that you write documentation so that someone (either you or someone else) will be able to read and above all comprehend what it is that you want them to understand. So you document some code because your silly hack will be completely jibberish to anyone — including yourself — within two months. You need the documentation so you can say to yourself (without lying) that this thing you've been doing is finally, truly done. You can forget about it entirely safely because if you need to do anything else with it later, you have some footnotes to explain it to you.

That's what I like the most about documentation. I can safely push things out of my mind when I know I can retrieve that knowledge later from the documentation I've written. Of course, I'd like to keep the knowledge in my head, but the way my brain tends to work only the high-level stuff stays in there and the implementation details fall out of my ears and get all over the carpet. So it's a given that I'll need my documentation.

Understanding that I'll eventually need documentation to pick up thoughts that I've left lying about the inside of my skull, I need to do something to make sure I'll actually care enough to read my documentation. For me, that means it needs to be short and to the point. In spite of what you might think of my verbose blogging style, I like to keep documentation terse. If something really is complicated enough to warrant documentation, it's going to be hard enough to understand without the addition of fancy vocabulary.

I break things down and organize them in a way similar to Wikipedia, allowing me to easily find definitions to things as I'm reading. So, for example, if KevBot made use of an SQL table, I would include the definition of that table in the documentation, so that I could easily refer to it when writing queries and insert statements against it. (Also, I use the DRY principle and use that documentation as the actual definition of the table so my documentation is never wrong.) Easy cross-referencing and always having the documentation I need at my fingertips makes my life a whole lot easier.

But documentation isn't just for code. Call now and we'll throw in documentation for games as well (while supplies last)! Video games! Board games! Role-playing games!

Video games, especially sandbox ones, require documentation so that you can leave messages to other players so they can understand your creations. For example, in Minecraft, I have made some kind of giant mechanical octagon which I documented with signposts so people can try to figure out how it works and so that I can maintain it if I ever need to add to it. Not that Minecraft allows for an optimal documentation experience, but at least it's something.

Board games, because you know you always need house rules. And if you just write down the rules themselves, you'll think that you were crazy to introduce/modify a rule like that. But if you supply the justification for why you came up with such a crazy rule maybe it'll make more sense. The problem is that while a lot of games that have built-in supplies for extending the rules (such as blank cards), they don't give you a lot of space to elaborate. So what I do is I just number the blank cards, then add an extra rules page that elaborates on the cards, explaining why the exist and how they can be used in detail. That way, if I want to have multiple sets of custom cards I can without having to buy new blank cards. So modular!

Role-playing games need a lot of documentation. Especially if you're running a game and double especially if that game is story oriented and features a lot of intertwining plotlines (this is what happens when I run a Shadowrun campaign — but elves are stupid, FYI (seriously who puts magic in a cyberpunk setting?)). When I run games, I have multiple sets of notes: persistent long-term goals for me, NPC character sheets, short-term campaign notes, information I can give the players, maps, etc. It's enough to drive anyone insane. Luckily, wiki software works perfectly for this sort of thing, so I can keep my notes online and fiddle with them anywhere.

In all of these examples, I try to keep things short and sweet, distilling the content down to what's most important for picking up later. I probably don't succeed as well as I'd like, but who cares? I enjoy it. This was a fairly long-winded way to say that it's a good idea to write things down so you can review them later. Good thing I wrote that down so I don't forget.