Collaborative documentation

In the category of "things I posted elsewhere that I want to preserve here"...

Stack Overflow began a documentation project, based on the idea that good examples are the core of good documentation. But the project ran into some problems, so they're "rebooting" it. They're going to focus on a single topic (T-SQL) to start, and are doing some user research before diving in. (And I got some warm fuzzies from the fact that they cited my SEDE tutorial.) But it seemed like some important points about documentation could be missed, things that frustrated me when I participated in the beta of the first attempt, so I weighed in:


Documentation doesn't exist in a vacuum; it exists because there are real people with real needs, and there's also prior work.

Regardless of subject, there are a few types of documentation, and when it comes to structure one size does not fit all. For example, there's tutorial-style documentation (like that SEDE tutorial), which introduces concepts as needed (just enough, not too detailed) while walking the reader through a progression of examples, which might have iterative cycles. Another type of documentation is the complete, documented example -- something that the reader can download and run himself, that has good comments and then some doc wrapped around it. (I don't necessarily mean one big <code> block; sometimes it's better to go method by method, for example.) Reference implementations are an advanced form of the complete, documented example.

Then there's conceptual documentation, where you explain in more detail what's going on with the different kinds of JOIN, for instance. And -- perhaps less relevant here, but I'll include it anyway -- there's task-oriented documentation, where you provide step-by-step instructions for how to do something procedural like configure Kerberos. What distinguishes task documentation from documented examples is that there should be fewer decision points -- getting that DB web front end up and running might require 37 steps but they're pretty much always the same 37 steps. That's different from doc about how to optimize a query, where you might be teaching a skill instead of providing instructions.

There's also reference documentation -- think API reference or language spec here -- where the focus is on being complete but comparatively terse, but where examples are also valuable. (This is probably not going to be where our best bang for the buck is.)

My point in saying all that is: these different types of doc require different enabling structures. This doesn't need to be a ton of work, but it's something to think about. We probably want something more than "here's a textbox" and less than "here's the schema for our fancy XML representation" -- maybe we just need some templates? Maybe the question about what T-SQL doc has helped people will evoke answers that touch on structure and organization.

One general point: being able to organize content is important. (Even better if it can be sketched out early on, before all the pieces exist!) In Documentation 1.0 examples on a topic were ordered by votes; there's no way to do a progression that way. A tutorial can involve several examples or example fragments, and they need to be orderable. It also won't make much sense for them to be evaluated (e.g. by reviewers) in isolation, away from their surrounding context. That's great for an initial code review, but you also need to be able to answer the question "is this a good example of that thing we just explained?".


That last point, about organization, was my biggest frustration in trying to help with round one of this. Somebody requests examples of Topic X, and a bunch of people throw some code at it, and there's no coordination, no logical ordering, and no way to develop a progressive example. There were lots of people involved but it didn't feel like a collaborative effort. Good documentation requires a little more coordination than that, in my opinion.