The Grand Unified Theory of Documentation

In case you went "hey, this looks like a blatant rip-off of Divio's pages, doesn't it?" -- yeah it is, because this is the spin-off of that particular aspect from Divio.

In regards to that four-quadrant infographic - how could Technical Reference fall into the category of "theoretical knowledge?"

I'd think tutorials would fall under theoretical because if it gets too practical, are you not effectively writing a how to guide?

I'm not really sure the four categories fit into that quadrant scheme as well as they'd like.

Doesn't the existence of blogs and Q&A sites like Stackoverflow indicate that current approaches to documentation are failing to deliver. I think there's more to the rise of cut & paste development than simply a lack of skill or a lack of time. The volume of state in some software systems is simply too great to put down in a linear document. Indeed the number of branches in state maybe too great to represent in any meaningful way or in any timeframe that's practical.

If you look at a framework like Django. The documentation is generally considered excellent. However now there is simply so much stuff that many complex things get only a cursory treatment. So everybody heads over to SO to find the question that is the closest fit to theirs.

I am not sure what would be better or indeed if there is any solution to this. The framework here layout a multidimensional approach with tutorials to get started and reference to follow up with. However creating documentation systems with that level of complexity is an enormous task and for anything of any quality, an enormous cost.

So what's the answer? I'm not sure there is one.

Some personal rules for docs:

1. Explain, in plain non-jargon words (nobody cares how smart you are) what problem is being solved, how, and why.

2. Provide contextualized examples (no foobar), not making assumptions about what the reader knows or doesn't know (and avoiding condescending language like "it's easy," "it's common sense" or anything that suggests the reader is "dumb" if they don't get it).

3. Think in terms of a blog post/tutorial, not technical API docs as a starting point. This helps with adoption because people want to understand the thing first and then dig into API (just because you may not doesn't mean that others are the same).

4. Don't be lazy. Show respect for the people taking the time to use your stuff and put in the effort (grammar, structure, quality of examples, etc).

My impression was that people went to SO to solve issues, and to documentation to think and build features.

I’d see those as complementary, and don’t expect documentation to cover most questions/issues you could have.