Documentation 2.0?

Alas, since this was posted the Stackoverflow documentation project has come and gone. The Documentary millennium is postponed for the forseeable future

I noticed recently that StackOverflow is trying to encourage community documentation. The tagline they’re using is “Let’s do for documentation what we did for QA,” which immediately made the cynical side of my brain think “like, turn it into a brogrammer mud-wrestling match?”

Kidding aside, documentation is something I’ve gotten to be very uptight about. Maybe it’s just having spent a the better part of a year having to maintain somebody else’s code. Maybe its the whiplash I’ve gotten from hopping between 3 game engines in 5 years. Or maybe I’m just setting into my grumpy old man persona and I want to stop answering the same questions about how to attach a control to a formLayout. But the idea of a good, relatively up-to-date community documentation is really appealing to me.

One of the things that really jumped out at me in the initial pitch on StackOverflow was the sentence

[Documentation] was usually written once, often by someone not even using the technology, so it was a guess at what to focus on.

which really rang true: I’ve generally run into only two different kinds of documentation: slick, well written and shallow — or spotty and inadequate. Those are not great alternatives. Easily 7 times out of 10 I end up on StackOverflow it’s precisely because I’ve found another hole in somebody’s documentation.

The idea that SO is pushing is effectively a kind of Wikipedia for their different communities: They want users to put together the building blocks and also to edit each other’s works — voting things up and down and editing them collaboratively more or less the way they do with SO questions.

To get a sense of where this is headed, you can check out the Python documentation page.

To me it doesn’t feel quite right just yet: the examples are fine on their own but I’m not sure I’d know how to assemble them into a coherent picture if I didn’t already know roughly how they fit together. On the other hand this is still new: give it a couple of years, with the incredible amount of free labor that the internet’s reputation economy provides, and I can see it being as good as the double-whammy of Unity’s docs and answer platforms. It’s particularly appealing to have a single place where a community can put the perennials: so many SO questions are just repeats of old questions where for some reason the asker hasn’t figured out the magic combinations of search terms to find the pre-existing answers. I hope that a good community doc site, with input from lots of people who know their way around, would produce a lot of folks who could efficiently route the clueless to the information — the answer might really lie less in the docs themselves than in creating a culture of people who knew roughly where to send people for authoritative info.

With that in mind I’d like to point out that there are currently only two people signed up to do documentation for Maya programming on SO — the site requires a minimum of five user before it will open a documentation site for a given topic. I think it would be great if the TA community led the way in getting the Maya documentation project into good shape. Not only would we all benefit from the information directly, we’d also have a chance to point new entrants in the field to a common source of knowledge that we all share in — over time I can see it becoming an important part of onboarding new TA’s into the business.

Plus, if it really works I can stop answering all those ‘how do I make this button update this field in Maya’ questions once and for all.

So, whaddya say gang? Who’s with me?