First, a little background.

I have some experience on Stack Overflow. One could call that a form of documentation. But I also am the primary contributor to another form of documentation: the OpenGL Wiki. I personally transformed it over the course of years from a dumping ground/crappy FAQ into a legitimate and genuinely useful resource.

Not to toot my own horn, but I think I know a little something about documentation.

The Forms of Documentation

All forms of documentation seek to provide knowledge. But the hardest part is knowing what form you need and how to index that form.

Reference documentation

The simplest form of documentation is what I call Reference documentation. These are often derided by newbies as being "only useful if you already know the answer." However, anyone with any real experience knows the importance of reference documentation.

Reference documentation is, essentially, taking each API or basic element of something, and explaining everything you can do with it. If you look up an API function's reference documentation, it should explain what the inputs mean, what the outputs are, and most importantly what the function does.

But the newbie's perspective on reference documentation is not unreasonable. Using my field of expertise (ie: OpenGL) as an example, take the function glTextureStorage2D. That is a solid piece of documentation. It tells you what the function does. Namely, allocating storage for a texture object.

Here are just a few of the things that it doesn't tell you:

• What's a texture object?
• What does it mean for a texture to have "storage"?
• What are mipmaps?
• What are array layers?

And here's the thing. No matter how important it is to understand those concepts, reference documentation should not explain them! That is simply not its job.

The newbie perspective is not entirely wrong: you absolutely must understand the basic concepts of a system before reference docs can help you. And it is important to have such documentation, because reference docs become a lot less useful if they have to spend lots of time explaining such concepts.

The strength of reference docs are also their primary weakness: when done right, they're assuming you already know a lot about the subject matter.

Another weakness is that it often involves a lot of duplication of information. Again taking OpenGL as an example, just look at the text on glTextureStorage1D and glTextureStorage2D. They are two separate pages, but they're almost identical.

Tutorial/Example documentation

Example-focused documentation is basically someone writing out some (presumably functional) code, and then explaining how it works.

Among the other things I've done for OpenGL is write this. I used to think of it as a tutorial, but I realize that it went quite far from being a pure "tutorial". One of the things I encountered while writing that was that I was constantly having to stop and explain how various elements of some feature worked.

Here's what I mean. In Chapter 2, I introduce the ability to interpolate colors across a polygon's surface. I explain that there are three ways to perform that interpolation: smooth (the default), flat, and noperspective. But... I couldn't really talk about the difference between smooth and noperspective. Why?

Because I hadn't introduced perspective projection yet. And without that, there is no difference.

I could have introduced perspective projection earlier, perhaps. But then I would have to hold off on having any per-vertex parameters interpolated across a primitive. That significantly limits the amount of stuff you can do.

I also could have introduced perspective correct interpolation when I introduced perspective projection. However, that chapter was already gigantic, and adding a seemingly random discussion about something that wouldn't be followed up on (the genuine uses for noperspective are few and far between) hurt the overall pacing of the work. It just didn't flow very well; it always felt kinda out-of-place.

The strengths of tutorial/example-focused documentation are that it's example-focused. The user sees code that they can download and run themselves. They get to poke at it to see what happens. And so forth.

The weaknesses of it are:

• They're generally no less impenetrable than references. Oh, there can be beginner focused tutorials/examples. But other than those, they will always assume some degree of familiarity with the subject matter. So beginners still need not apply

• Unlike references, they're usually not comprehensive. It's hard to provide a single example that comprehensively explores a subject. I'm more-or-less an expert in OpenGL, and I could never write a single, simple example that explores everything that glTextureStorage2D does.

• They can require a lot of boilerplate. Let's say I want to write documentation for how image load/store works. Well, I can't just do that; I have to contrive an example. I also have to create and possibly load images.

• They often have requirements other than code. OpenGL is a huge offender here, because to do anything beyond toy examples... you need data. You need meshes. You need textures. You probably don't want to write all your shaders inline, so you need files for them too. Web applications often have database needs. So even if you write an example, how do you deliver it? How do you deal with the large number of C and C++ build tools that exist? Is it just code on a website or is it something people can run?

Concept documentation

Unlike the others, the nomenclature for this is purely mine.

Concept documentation refers to documenting, not the individual behavior of a system's APIs, but the behavior of a system's concepts. That has been my general goal with the OpenGL Wiki: each page is about different concepts of OpenGL. Indeed, the only reason I imported the reference pages into the Wiki was because filing bug reports to get references fixed was (and still is) taking way too long.

Concept documentation fills a very important gap. Unlike reference documentation, it focuses on concepts within the system. Unlike example documentation, it can explore a concept comprehensively. My goal in writing, say, the OpenGL Wiki article on Vertex Shaders is to explain everything about them. Every option is presented, either directly in text or with a link to more details.

It is also a very searchable form of documentation. Not the OpenGL Wiki, but that's more due to MediaWiki's search being crap. If the user is reading a

Conceptual documentation is often bundled with reference documentation. In Doxygen parlance, these would be written as either Pages or Module/Group documentation. The Direct3D documentation has a reference section and a conceptual section, though the concepts tend to be more of an overview.

The weaknesses of this documentation form are:

• It can involve a lot of text duplication, in the desire to be comprehensive. I ran into this a lot in my work on the OpenGL wiki. I try to use MediaWiki templates and other magic to reduce actual textual duplication where possible. For example, the Vertex Shader page has a section that describes the built-in inputs to the VS. But there is also a page that describes all of the built-in variables for each shader stage. Both pages are separate concepts, but share some data. So I made a sub-page and simply included it into both pages.

• It's hard to know where to start when you want to read through concept documentation. Concepts often refer to one another, but there's no logical beginning point. I've tried several times to come up with a starting point for the OpenGL Wiki, but as you can see from the main page, the best I've been able to accomplish is a giant list of links.

• Even if you explain everything about one concept, you still haven't necessarily explain how they all fit together. Example/tutorial documentation is better at assembling the pieces.

Learning materials

These are tools you're meant to read from beginning to end. You're expected to know more or less nothing when you start.

These are typically books, written by actual authors.

On Documentation.SO

I submit that, while each form has its flaws, every form is important. There is a time and place for each form of documentation.

But Stack Overflow is different. SO is collaborative. So, which documentation forms fit into that collaborative ideal the best?

Reference documentation

This fits quite well. Once thing about collaboration is that it has to effectively work with drive-by users. Someone who isn't really invested in helping, but maybe they have a few minutes and wants to drop something off.

Reference docs make that happen. There is very loose coupling between different reference pages, so they can get filled in quite quickly. The C++ reference site is probably an excellent example of this. 3 years ago, it was nothing. Now, it easily crushes cplusplus.com as the go-to site for standard C++.

It is also good when dealing with curation. That is, it makes it easy to accept changes, and then have those changes smoothed out by the much smaller number of primary editors of the site.

Tutorial/Example documentation

On the one hand, a person can write an entire example and document it by themselves. But on the other hand, editing someone else's examples become a problem.

You will get code style wars; mark my words. You will get people who absolutely cannot stand one particular indentation style or whatever, and they'll just go in and "fix" it. Or worse, you'll get lots of different coding styles across examples.

I think a bigger problem here though is the lack of comprehensiveness. And OpenGL makes for a good example of this.

How many OpenGL programmers can write an example of buffer object usage? Lots. How many can write an example of Image Load/Store usage? Far fewer.

Which means that you're going to get lots of examples of ways to do easy/trivial stuff, with very few examples of the harder things the API offers. You'll see plenty of examples for "my first texture", but far fewer for "projective texturing". What's worse is that you could get examples of shadow mapping without examples for projective texturing, even though projective texturing is required for many forms of shadow mapping.

I just don't think a tutorial repository is going to work collaboratively.

Concept documentation

I think this can work collaboratively. Wikipedia is a great example of concept-based documentation being created and edited collaboratively.

It also shows many of the potential pitfalls of it. Everyone wants to put their own stuff in, but nobody wants to organize it. You'll never be quite sure that it's truly comprehensive. And so forth.

Learning materials

Good God, no!

Again, leveraging my authority on the subject, I would say that building learning materials by collaboration is a doomed proposition. A good work for learning requires planning and careful consideration of what new users do not know. At the very least, a good learning work requires someone coming up with an outline.

See, the best learning books introduce ideas, then build on them more and more. With each step, they add new concepts, but they are built upon previous ones.

I structured my "tutorial" series very carefully in this regard. Or at least, I tried to. Each tutorial tried to use functionality that was introduced in the previous one, and thereby reinforce lessons learned before.

That's not something you can do collaboratively, among a group of equals. That's something that 1-3 people need to sit down and actually accomplish.

Required technology

Making good documentation in HTML is easy. Well, it's possible. Making good documentation in not-HTML... that's a bit harder. Each documentation form has its own needs as far as formatting, and not all of them are available in Markdown.

Reference documentation

Reference docs are centered around API functions. Even class-based docs like JavaDoc or Doxygen are still centered around the documentation of each function. So there must be some way of formatting function signatures.

Of course, every language has its own needs for function documentation. That's going to be a nightmare to work out in terms of formatting. DocBook makes a good show of it in its funcsynopsis type, but even that is focused on languages that look like C.

Not to mention, functions are often aggregated into classes or just conceptual groups. Not only does this need to be a part of any reference documentation scheme, it has to be able to import part of the function's documentation. This allows Doxygen/JavaDoc-style brief documentation that gives a quick summary of the function.

There has to be some facility for dealing with overloads. This is the absolute bane of Doxygen; having to find a way to document 5 functions that all have the same name, but different parameters. It wants to make them 5 separate entries, but no human being actually likes that. If Documentation.SO wants to handle reference docs, there must be a solution for this.

I guess my point is that formatting is really important for this, and not having it isn't optional.

Tutorial/Example documentation

The formatting needs here are actually quite minimal. The reason being that we already have more or less what we need: the ability to write blocks of code in a specific language.

Probably the biggest need that isn't available is some form of callouts. That is, the ability to label specific locations in a code block, and later refer to them in your text.

There's also the issue of breaking examples up. For longer examples, you will often want to present part of the example, talk about it, then present another few lines, talk about that, etc. So... how do you download the whole thing? Does there have to be code duplication, where the user writes the code into markdown and into some source file?

Concept documentation

There are fewer technology needs here, but there are still some needs.

First, as I experienced on the OpenGL wiki, inclusion is crucial. Being able to include a page in another page makes the whole thing far more legible. There are many articles on the wiki that, if you turned the inclusion

Also, linking needs finer granularity than "article". Section linking is crucial. At the same time, it's important to be able to turn a section into an article if it's become too big. MediaWiki's ability to make redirection pages helps here. You don't link to sections directly; instead you use redirects to go to needed sections. I imagine that they could come up with other solutions, but there does need to be some solution.

Oh, and the ability to manipulate the wiki with external tools is also important. Again, I speak from experience. I have made many "bots" for the OpenGL wiki, and the ability to rename pages alone made leaning some small bit of C# worthwhile.

Also a tool for automatically building a glossary would not go unused.

Learning materials

Who cares; we shouldn't be trying to do that anyway.

The take-home point

Documentation is hard. Specific kinds of documentation exist. Some can be built collaboratively, and others cannot. And they all have technology needs that Stack Exchange doesn't provide yet.