Thoughts on Stack Overflow’s Documentation beta
Beth Aitman

As a fellow tech writer, I concur — you’ve identified a lot of the things that make documentation challenging.

In a post on Meta SO I wrote about another aspect of the problem:

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?”.