With documentation that’s easier and (theoretically) better for all
I’m sure there are lots of ways to handle documenting things (design documents, release notes, requirements, etc.) in a software development environment, but I’ve only ever seen 2: a corporate wiki, and something from Microsoft (I forget the name of it, all I really remember is that it had a check out/check in model, and all the developers thought sucked. I’ll just call this option “the Microsoft option” for lack of something more accurate). From what I’ve seen, wikis have a lot of promise, and do a great job, but to live up to their full promise they still require an anal retentive developer dedicated to periodically reviewing and fixing the documentation for anything they actually deal with on a day-by-day basis.
First I’ll talk about the Microsoft option, and explain why it sucks just so it’s clear that I’m not saying that it sucks simply because Microsoft made it. Here was the basic scheme – you logged into their service and selected whatever project you were working on (we didn’t have access to the other projects, but in all fairness, I seriously doubted any of us would have cared enough to read that documentation if we did). If you wanted to edit a document, you navigated through some directory structure that I’m sure made sense to someone, just never to me (and I’m not entirely to the same person at each level you navigated through), until you got to the document you wanted to modify. Then, you checked the document out (if you wanted to use the “Edit in Word” option, which would automatically check out the document for you, you had to use IE, specifically IE6, and no, it wasn’t long enough ago for that to be an acceptable option), then you downloaded the document, then you edited it, saved your edits, closed Word, uploaded the edited document, and checked it back in. So far, just a lot of clicks, some outdated browser requirements, but nothing too serious. But that only applies if you knew where the %^(&ing document was in the first place. I swear search on this thing was one of those placeholder functions that just puts some stuff on the screen to verify the principle of displaying results if a user clicked the search button, but the actual feature never seemed to be implemented. You were more likely to find something manually clicking through folders than actually searching. Because nobody knew where anything was, nobody updated anything if things changed. As a result, anything you did find on that site was probably outdated anyways. We didn’t even bother pretending about things like revision history – those files never got changed once the stuff they talked about was initially implemented and shipped.
Now let’s compare that to the corporate wiki model. Very little clicking around to find things there – pull up the wiki, search (sweet, blessed, actually-works-and-returns-useful-stuff search!) for what you need, and there it is. The only time where it isn’t more convenient to search for something, is when that something is linked on the wiki home page. Because we can easily find stuff, it’s pretty easy to make sure things are updated by whoever notices the problem. When I started my current job, I corrected various sections of the VM setup guide on our wiki to reflect how things worked then. No checking out/checking in, no downloading/uploading, just edit the document and it’s there and updated for everyone. It’s easy, simple, and it works perfectly, when people do it.
Where you able to guess what the operative phrase was in that last sentence? Wikis are only as useful as they are up-to-date. Given how gung-ho most developers I know are about writing documentation, that’s not the safest bet in the casino. At least with a wiki, when the documentation sucks, it’s at least easy for whoever stumbled across the bad documentation to fix it. In fact, if your documentation is in wiki form, there is never any excuse to not fix bad documentation as soon as you encounter it. It’s this philosophy that keeps the granddaddy wiki, Wikipedia, more accurate than you would assume given the low amount of friction involved in vandalizing the site. If you’re doing anything in your code that has documentation tied to it, getting into a habit of doing a quick sanity check/update is probably a good new year’s resolution for 2013 (it also gives you a couple months more to utterly ignore trying to maintain documentation, which was probably going to be your first instinct anyways).
In a perfect world, documentation would be easy to update, and always accurate. In reality, most of us don’t think to pull up the documentation for anything we’re working on, and as a result, never bother to update it when we make important changes. Wikis solve part of the documentation problem, namely being easy to search and edit, but they still don’t solve the problem of developers taking the time to find and check the documentation they’re producing. Ultimately, solving that requires 1 of those irritating “changes in personal habits” that suck so much to do. The end result, however, is a living, breathing documentation guide that’s always correct and thus always useful. Well, that’s the documentation wiki dream, at least.