Skip to main content
6 of 6
Commonmark migration

Looking at the Google Docs list of announcements and description of the site, I have to say that I find myself... rather disappointed and confused as to the whole purpose of this endeavor.

The part that I'm concerned about is found in The Tour section:

The most important, and only mandatory, set of pieces are Examples. Examples demonstrate how to use whatever is being documented and need to be self-contained (ideally copy/paste-able) and succinct.

Examples embody Show, Don’t Tell. A Topic will live and die by its Examples - a good Topic is one where most people don’t need to do anything beyond scan one of the Examples to find what they need to know.

So... what exactly is Documentation.SE? Is it intended to be some kind of code dump of examples? I don't understand what a "topic" is, if a topic must be a thing that's small enough to have a code example associated with it.

Maybe my field of expertise, in terms of documentation, is somewhat narrow. My primary experience in this field is writing the OpenGL Wiki, which tries to describe the functionality and behavior of various parts of the OpenGL API.

I cannot imagine how I would structure that information in the "code-as-topic" style that you seem to want. Or, more to the point, I have no idea how to present information as complicated as things get in OpenGL in such a style.

Let me put it this way. This is the OpenGL Wiki article on "Vertex Shaders". How do you break this down into "topics"?

If we're doing "code-as-topic", then you can't have a topic called "Vertex Shader". Why? Because Vertex Shaders are huge, complex beasts. They're written in an entirely different language, interact with vertex specification and rendering commands, feed data to later rendering pipeline stages, and so forth.

Oh sure, you could write an example of a Vertex Shader. But I guarantee that any user who has no idea what a VS is, will have no more idea of what it is after reading an example of one. Or five examples.

So maybe you could break down the bits of a VS into several topics. Could Vertex Shader Inputs be a topic? I don't think so; it's going to involve two separate things: the in-shader declarations, and the corresponding vertex array code that feeds them. It's also going to have to involve the rendering command, since instancing can adjust the meaning of a VS input.

Is there a way to make a topic around even one small aspect of a VS? Take the built-in input gl_InstanceID. How can you make that a topic?

You can't. Again, you can write an example that shows it being used. But because of the complex interactions between gl_InstanceID and the rendering command that touches it off, you will need a large number of examples to cover the important information. And even then, you won't actually cover that information meaningfully until you explain what's happening in the code examples, which is a section at the bottom of the page.

Even documenting a single OpenGL API entrypoint with "code-as-topic" seems insane. There is no one example of a function like glTexImage2D that can possibly capture the sheer scope of what that thing does. You could have dozens of examples and still not cover everything. None of those examples could be "copy/paste-able".

And quite frankly, we have enough copy/pasting going on in the OpenGL community; we really don't need to encourage more.

Even if you change the topic from "document glTexImage2D" to "create a 2D texture"... well, how do you do that? Even ignoring the versioning issue, the number of options for creating textures is legion, and it's not restricted to the parameters of a single function. Does this texture have mipmaps? What image format do you want to use? Are you creating a compressed texture?

Are you uploading pixel data? If so, what's the format of that data? What about the pixel alignment, or uploading sub-rectangles?

Should the example apply sampling parameters to the texture, or should it be assumed that users will use explicit sampler objects? If you want to apply sampling parameters, that's a whole other mess of options.

Oh, and none of that will ever explain the most important part of creating a texture: what a texture is. An example cannot convey important information like the fact that a texture is composed of 3 parts (storage, texture parameters, and sampler parameters). It can only show the code; it cannot show the meaning behind the code.

Just as your example for Query can only show the code calling it; it cannot show what that particular query actually does with the database.

And be aware that this is just OpenGL. AKA: the easy-to-use graphics API. God help you if you try to apply this style to Vulkan! "Ideally copy/paste-able"?

Yeah, good luck with that.

I simply do not understand how this "code-as-topic" style will accomplish anything useful for any system of real complexity. It's like telling someone to write a tutorial that is short, self-explanatory, comprehensive enough to be useful documentation, and somehow "copy/past-able" for user consumption.

So exactly what kind of documentation is this site for? If this site is for reference documentation, for documenting function calls, then why are they called "topics" and not "functions"? And why put the example first? Must functions that are complex enough to deserve reference documentation are too complex for one example to explain its full meaning. And having to sift through a half-dozen pieces of code before finding one that actually explain what it does is rather silly.


(Collation of commentary information)

The rough philosophy here (and I'm probably butchering Kevin's vision, but...) boils down to, "a practical example is worth 1000 words of explanation".

This is a documentation style that does not work for anything but the most basic of systems.

In any system, there will be many things which cannot effectively be conveyed by examples. For example, let us consider the OpenGL Wiki article on the Incoherent Memory Accesses.

You could take the "guidelines and use cases" section at the bottom and construct examples of them. And in that way, you would indeed have code that someone could use in their application.

But do not fool yourself into thinking that anyone who reads such examples actually understands what they're doing. Such people will still have no idea of the complex interrelationships between such operations. The concepts of asynchronous memory access, synchronization, and visibility are highly in-depth, and code examples are not an effective way of conveying such information.

If Docs.SO's example-focused topics are not designed to be able to fully convey the behavior of a system, then I would say that it has a poor design. You can't replace something that doesn't work with something else that also doesn't work.


There are a couple misunderstandings here, which is understandable since few people can actually see Documentation yet. Topics have Examples, Topics are not necessarily small enough to be covered by one example; your OpenGL link is already logically a Topic best I can tell (I'm not an OpenGL expert).

OK, let's investigate that.

First, your own documentation seems to argue against the idea of multiple examples of importance. And I quote:

If a Topic feels like it needs more than one Pinned Example, that's probably a sign that is should be broken up into multiple Topics.

So clearly there is intended to be a single, canonical example that exemplifies a topic. There can be subsidiary examples that perhaps fill in a few blanks. But there is clearly an intent for a "Topic" to be a thing that is small enough to be mostly encapsulated by a single, canonical, pinned example.

So there seems to be some disagreement between you and... you. Should a topic contain multiple examples of more-or-less equal standing that explain a topic? Or should it contain one major example, with a few minor ones to flesh out a couple of details?

If it's the former case, then pinning (and voting in general) seems like a misfeature.

But there's more to than that.

Regardless of the kind of documentation, the order in which information is presented is absolutely crucial in writing effective docs. Reference documentation will generally put the function signature first, because seeing parameter names/types will answer about 80% of questions that users would seek out reference documentation for.

If a topic is sufficiently large that it needs to have multiple examples in order to fully explore the breadth of it, then which ones come first is very important. But the problem is this:

There's no one right answer to that. Which ought to come first depends on the audience.

A beginner who found reference documentation will see a signature and be put off. Why? Because they have no idea what to do with that function. Whereas someone who's looking for syntax will see the signature and get what they need. Reference documentation is optimized for the latter, not the former.

So who is Docs.SO optimized for? And most importantly, who decides what it is optimized for?

Docs.SO has two means of controlling the order of examples: pinning of examples and voting on them.

Pinning is, according to your document, something that the creator of the topic has complete control over. Nobody can override such a person's judgment.

Which means that the person who has overriding control over who the audience for a topic is will be the creator of the topic. That seems... wrongheaded.

Non-pinned examples will be shown in order of their vote totals. Which means that the decision of who a topic serves best will be decided by voting. Except that people won't vote in that way. They will vote based on whether they like an example, not whether it serves some expected audience.

This means that Docs.SO has no means of deciding how to best present information for a particular intended audience.

That's bad.

Nicol Bolas
  • 471.9k
  • 61
  • 186
  • 279