183

Six-to-eight weeks Several months ago we proposed an expansion to Stack Overflow: Documentation. People have been asking for an update for a while, and we’re finally ready to give one.

The beta has been underway since mid-November, and at time of writing about one thousand invites have gone out. If you signed up but haven’t been invited yet, don’t worry - everyone who signs up will eventually get an invite.

We’ve learned a lot in the beta and now have a decent idea for what a V1 looks like for Documentation. Accordingly we also now have a good idea for about when the beta will end: sometime in April.

This means beta signups will be closed on March 31st

The beta itself will continue for a bit after so those last few signups can get invited. Documentation won’t be going live on Stack Overflow on April 1st or anything like that.

What’s new?

There are a bunch of features that either weren’t ready when the last post went out, or that the beta showed us we needed.

In no particular order, here are some of the more notable additions:

Pinned Examples

Pinned examples

Each Topic can have its most important Example pinned to the top; the rest follow in vote order. We believe a Topic having more than one "this is the most important" Example is a sign that the Topic needs to be broken up.

Reputation System

There are lots of little details, but the TL;DR is:

Reputation tour

Naturally you can't give yourself reputation, and deletions snatch back reputation in a similar manner to Q&A. Reputation will be shared with your Stack Overflow Q&A account once Documentation is out of beta.

NOTE: +5 reputation on cited documentation can be gained for a (Topic|Example)+Answer pair.

Search For Documentation from Q&A Editor

New link insertion

This make it easier to find Documentation to link to while answering questions. The current "Insert Hyperlink" is still the default naturally.

Links Can’t Break

I think everyone can agree that broken documentation links (be they in code comments, blog posts, tweets, or whatever) are super frustrating. Of course, you still want Documentation (and the search results that point to it) to improve over time.

The design we’ve settled on is:

  • We always serve the latest versions (including 404s for deleted Topics) by default
    • this means Google only serves up the latest stuff
  • But if you have an old link, we offer to show you the "when that link was created" version

For old versions of non-deleted Topics, this looks like:

Topic has since been edited

Deleted Topics look like:

Topic is currently deleted

Deleted Examples look like:

example is currently deleted

Viewing an older version includes a little notice at the top, disables editing, and doesn’t allow voting:

Viewing an old version

Lots of notification options

The obvious ones are done:

  • My change was approved/rejected
  • A change to fix an issue I raised was proposed
  • Someone commented on my issue or change
  • Someone replied to one of my comments

Sections on Documentation Dashboards can also be subscribed to:

Notification eyes

When subscribed to a section you get at most one notification per time period. If there are multiple things to notify about, we make sure each item is sent to about the same number of people. If the notified item is handled before someone views their inbox, we delete the item to prevent pointless noise in their inbox (there’s a natural race here, so we can’t be perfect but we do what we can).

Deciding which tags get Documentation

We’ve landed on an Area 51-lite approach. To avoid creating ghost towns, we require a minimum number of users who are already active in the tag to commit to working on Documentation.

In beta this looks like:
what commitments looks like

On Stack Overflow we’ll raise the bar to:

  • 10 users
  • with 150+ reputation
  • with at least one positively scored answer in [tag]

Committers get auto-subscribed when a tag's Documentation opens up, so there'll be people around to handle any improvement requests or changes right from the start.

And a bunch more!

This post is getting pretty long, but there is more! We’ve been doing semi-regular announcements in the beta. I've cut them down and put them all (in reverse order of release) into a public document.

Of course if you want firsthand experience...

Sign up for the Documentation Beta

...by March 31st 2016.

48
  • 111
    Documentation won’t be going live on Stack Overflow on April 1st or anything like that - is that because no-one would believe you anyway? :p "Hey Guys, Documentation is going live on April Fool's Day"... "yeah yeah - we believe you SE..."
    – Jon Clements Mod
    Commented Mar 18, 2016 at 18:12
  • 2
    @undo correct - waiting until the next wave of invites goes out to create a few dozen Q&A tags to try it out with. Couple folks on the team were out this week, makes timing tricky. Commented Mar 18, 2016 at 18:23
  • 65
    On behalf of the remaining preservationist contingent, I'd like to thank you for considering the accessibility of deleted content from the beginning. :) The solution you've implemented is very sensible. Ensuring that all links include a reference to a specific version, while still showing the latest by default, is a great way to balance concerns around link rot and stale content. Commented Mar 18, 2016 at 18:37
  • 14
    I think everyone can agree that broken documentation links ... are super frustrating. Especially when they are links to deleted SO questions :-)
    – Slapout
    Commented Mar 18, 2016 at 21:06
  • 7
    Since links can't be broken, will link-only Q&A answers linking to Documentation eventually be considered "okay"? Commented Mar 18, 2016 at 23:43
  • 6
    "To avoid creating ghost towns, we require a minimum number of users who are already active in the tag to commit to working on Documentation" can we do the same for tag creation on the main site, pretty please?
    – Braiam
    Commented Mar 19, 2016 at 0:09
  • 5
    @PetahChristian For iOS, I would hope something like NSHipster's codeblocks would be implemented, where you can choose between Swift and Objective-C right next to the code.
    – tktsubota
    Commented Mar 19, 2016 at 1:19
  • 4
    The initial announcement for Documentation was met with a whole lot of negative/critical feedback. Have any of those concerns been addressed? It looks like this update is focused on polish and features, with no mention of fundamental issues like whether it's a good idea. Commented Mar 19, 2016 at 4:25
  • 7
    @Braiam: "can we do the same for tag creation on the main site, pretty please?" That would make no sense. How could you have a minimum number of users using a tag if the tag does not exist yet? Docs.SO is linked to the tags on SO. Commented Mar 19, 2016 at 13:34
  • 3
    Is the documentation reputation shared with the Stack Overflow rep?
    – poke
    Commented Mar 19, 2016 at 17:09
  • 12
    Honestly I am a bit unclear what this documentation thing is about? Why is it needed? What problem does it solve??? Commented Mar 20, 2016 at 14:10
  • 6
    @MichaelB There's a balancing act. We could have just built and launched Documentation, no warning. I think we can all agree that would have been a disaster. We could have done a soft-launch with a system that didn't work, and try to let the community help us iterate to one that does. I suspect that would also have been a disaster, based on cadence and fatigue in the beta. Our middle path (a pre-beta dialog, private beta, pre-launch dialog) is, in my opinion, the best option but there is plenty of room for misunderstanding. Commented Mar 20, 2016 at 21:27
  • 2
    @Benjol It's their proprietary algorithm for sensing obsolete content :-D
    – TylerH
    Commented Mar 21, 2016 at 13:28
  • 2
    @KevinMontrose In that case, what about closing questions as "duplicates" of Documentation examples? Otherwise it seems like there will still be lots of redundancy. Commented Mar 21, 2016 at 14:34
  • 3
    Hmm...when are the remaining people going to get invited? I signed up and still have not received an invitation email.
    – tktsubota
    Commented Apr 3, 2016 at 15:59

4 Answers 4

157

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.

41
  • 44
    "most important ... ideally copy/paste-able" Yuck. I kind of regret requesting an invite now. Commented Mar 18, 2016 at 23:01
  • 35
    Hate to state the obvious, but... This is why it's still in beta. Private beta. Until enough folks with different needs get a crack at using it, we're really not gonna have a solid idea of what's needed or missing. The OpenGL example (kudos, btw) would hardly be better served by MSDN / JavaDoc style docs, and yet I've seen and suffered through such a thing; this is a different approach, and only time - and use - will tell if it's viable.
    – Shog9
    Commented Mar 19, 2016 at 0:24
  • 48
    @Shog9: OK, but... what is the approach? I don't understand the approach. Even the example given for Query was so thin it was transparent. It offered nothing over MSDN/JavaDoc/Doxygen. To put it another way, what is the mission statement? SO had clear guidance from the beginning: use Q&A to build a knowledge base. What's the guidance for Documentation.SE? Commented Mar 19, 2016 at 0:37
  • 15
    If the goal is to make documentation that is better than MSDN/JavaDoc/Doxygen, then it seems the focus on examples is just the wrong way to fix the problem. The problems with such documentation is typically that they lack some information, that they're not comprehensive enough. It has never been "there weren't enough examples". Commented Mar 19, 2016 at 0:41
  • 8
    The goal is very much not to make a better JavaDoc than JavaDoc; there are already plenty of efforts toward that end. 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". IOW, MSDN and such are typically full of examples... of things that no one would ever actually do, or at least, do in the way being illustrated. They're the Monty Python Dirty Hungarian Phrasebooks of documentation. SODocs is attempting to approach this from the other direction.
    – Shog9
    Commented Mar 19, 2016 at 0:49
  • 24
    @Shog9: "a practical example is worth 1000 words of explanation" OK, but what about APIs that, as I just explained, do not lend themselves to "practical examples"? And what about the Query example, where the "practical example" was garbage and basically told you nothing about the complexities of a database query? At the end of the day, I simply do not buy into this philosophy of documentation. I've seen far too many programmers who think they know something about a function call thanks to copy-and-pasting "practical examples". It's like giving a child a shotgun. Commented Mar 19, 2016 at 1:01
  • 7
    The truth of the matter is, those programmers aren't reading good documentation today, @Nicol. They're reading Stack Overflow. So what's the solution to that?
    – Shog9
    Commented Mar 19, 2016 at 1:03
  • 25
    @Shog9: "those programmers aren't reading good documentation today" So you're saying that every tutorial on the Internet sucks, but that your tutorial will be fine? That's what we're talking about. Example-based documentation is tutorial documentation. I don't buy that Stack Overflow is some salve that magically turns bad ideas into good ones. If people are failing to learn properly from tutorials, and have been doing so consistently for years, then the problem is with tutorials as a concept. And the form of Docs.SO you are describing is simply tutorials minus the explanation. Commented Mar 19, 2016 at 1:09
  • 63
    @Shog9: Also, if examples are so good at explaining things, then show a good example of Docs.SO working. Commented Mar 19, 2016 at 1:09
  • 9
    I refuse to believe that SO Documentation boils down to "monkey see, monkey paste." That's not documentation, that's ActiveState. This can't possibly be so ill-conceived. Commented Mar 20, 2016 at 8:54
  • 5
    Examples aren't just code (they're full-markdown blocks, like Answers), and the "succinct, self-contained, copy/paste-able"-guideline is roughly inline with Q&A; code should "work," though that doesn't necessarily mean "compile and run without modification". It is just a guideline (and one I think ought to be rephrased now, based on this discussion), for some topics or examples it won't be necessary. Commented Mar 20, 2016 at 21:02
  • 10
    @KevinMontrose: "as you've latched onto a particular vision that doesn't quite match reality I think." I've latched onto nothing. I'm simply using your description of the site to try to understand it. It's not my fault if your description of the site doesn't match reality. It is a poor teacher who blames the student for not understanding. And a very bad trait for someone who wants to write a documentation site. Commented Mar 20, 2016 at 23:51
  • 33
    Nicol, I am in the beta, and your remarks match my concerns. I posted a question (that you can't see) entitled "What about 'why'?", where the only (non-official) answer I got was pretty much "we should just focus on the 'how'". I find this frustrating because I would like documentation to communicate understanding, not just information. Code examples are the first class citizens for the moment. It all seems to be based on the premise that most users will read code, but not prose. Unfortunately, this is probably true.
    – Benjol
    Commented Mar 21, 2016 at 6:17
  • 4
    So @Kevin, I think what I'm asking for is here, where you can currently choose between for example C#, Java and .NET, we need a few cross-cutting root-level categories, such as "Networking", "Files", "Databases", "Graphics", and so on. Those are platform- and language-independent, and are needed to link to (and include from) from language-specific docs, in order to not repeat oneself and collaboratively improve it. I see such topics become more Wiki-like, with less code (or pseudo) but more explanation of principles - aimed at developers.
    – CodeCaster
    Commented Mar 21, 2016 at 9:53
  • 9
    @DerreckDean: "it may not be perfect but so far it sounds better than what similar tools that are already available" Really? A random bunch of tutorials, with neither explanation nor proper ordering of information, sounds better than what already exists? Quite frankly, you could learn more about OpenGL from the horribly outdated NeHe tutorials than what Docs.SO would provide. "without giving a solid foundation on how to make it work" ... so? You may not know the right way to get from New York to Los Angeles, but you can know that taking a flight to England isn't it. Commented Mar 31, 2016 at 14:59
66

Reputation System

There are lots of little details, but the TL;DR is:

Image

The Google Doc expands on this:

  • Upvotes on Answer that cite Documentation you have contributed to (+5)

I don't like this. This will cause two large problems:

  1. Users who only care about reputation will only contribute to the popular Documentation pages and ignore the rest.
  2. Users who don't need a reputation incentive (who are probably the ones you want contributing to the Documentation site) will lose out because compared to those users they'll be the ones writing the less-popular Documentation pages which are barely ever linked to.

I'm looking forward to having the opportunity to contribute to the Documentation site, but I don't need any reputation incentive to do so. I'd also much rather know that the people who have contributed have done so out of a passion for whatever it is they've written about, not because they can get a pretty green +5 every so often.

9
  • 6
    Alas - but the same can be said on vampire-feeders on SO. This has been discussed over and over, but there is no good solution. I think the same goes for your (admittedly, slightly worrying) argument. Unless there is some max on how much rep can be gained from a single topic, maybe?
    – Jongware
    Commented Mar 19, 2016 at 23:15
  • 2
    How is that a problem, exactly? Users in group (1) will be disinclined to mess up less popular documentation (while any harm they do to more popular docs is sure to be noticed), and users in group (2) by definition don't care. (For the record, I was in group (1) for a while --- and I think I did more good than harm.... --- but then I saw the light.)
    – jpaugh
    Commented Mar 20, 2016 at 8:08
  • How about changing the reputation awards to some badges award, and add some ranking system like the Review page.
    – J3soon
    Commented Mar 20, 2016 at 8:21
  • 14
    One nuance loss here, you can only get Reputation once for a (Topic|Example)+Answer pair. The "optimum" behavior if you're chasing rep is to contriubte to often-cited docs... which is pretty OK I think. There are "minimum substantive changes"-checks, and all changes go through a review process, so it's a pretty high bar to get into those docs. Commented Mar 20, 2016 at 21:12
  • 7
    Total reputation potential in a [tag] is proportional to activity in that [tag], by design. That's true on Q&A and will be true in Documentation. The idea being that you get rep for helping people with real problems, so naturally the most rep will be available from the places people are experiencing the most issues. Commented Mar 20, 2016 at 21:13
  • 9
    I'm confused, is point 2 really that "High rep users don't care about rep but will miss out on not getting rep"? Commented Mar 21, 2016 at 9:33
  • 2
    @KevinMontrose I don't think that theory will hold in the long run. After a point a topic will be pretty much as completely explained as it will ever be. There's only so much you can say about Hello World before you're just repeating yourself. Newer topics will always be the ones getting the most edit activity because they're new.
    – TylerH
    Commented Mar 21, 2016 at 13:47
  • 2
    On the bright side, Doc.se can act as a honeypot for both vampires and feeders. Just not very useful for the rest of us.
    – prusswan
    Commented Mar 28, 2016 at 11:41
  • It's not reputation which is the incentive, it's validation from other programmers which is the incentive. If you're able to validate your own actions without input from others, then that's a blessing. There's no need to ruin other peoples' incentive though. There's no need to be jealous. Commented Jul 24, 2016 at 0:25
31

My personal hope for SO Documentation is that SO is giving us a bag of spanners, and letting us have the say of how we use them to build a documentation site. So while example based documentation is clearly important in the beta version of documentation, once it actually goes public and the community can start having a say about what it does / doesn't like then we start figuring out what to do with it.

Just to continue the example conversation a little, I think that example based documentation is very important, and will very likely be the first page that most people arrive at from a search engine.

But behind that example, there needs to be solid documentation about the theory and concept of what is going on in the examples. Someone picking up an example needs to be able to go deeper with it. Otherwise it is just another box full of examples with a complete lack of depth, and the internet has got plenty of those already.

I think this will be the part that the community will begin to shape once it is launched. It should become a very interesting conversation about what good documentation really is, and how we can achieve it as a community.

and for as much as I'm looking forward to what SO Documentation might become, I'm looking forward to that conversation a lot more, because I don't think it has ever been had before. I think a lot of people have made a career out of saying what good documentation is. I'm not sure that ever made it so though...

2
  • 1
    Couldn't agree more. Code examples are great for syntax/usage of a method, algorithms, etc... But that's dealing with the minutiae and implementation. We should also try to document the concepts / philosophy behind the system/framework/language's design. That's where an awful lot of the valuable knowledge lies. Finally, I don't believe someone who already struggles to find a code snippet via Google is likely to find SO Docs any more easily, so question the value of prioritising snippets.
    – Basic
    Commented Apr 1, 2016 at 19:38
  • 2
    @Basic One of the first programming books I ever read (It might have been kernighan and ritchie c book - or not!) but it had a lot of anecdotes of 'we implemented it this way because doing it that way broke something else' I understood that language far better than any other I've learnt because I understood the reasons for the language choices and not just x keyword comes after y keyword. While we might not be able to add that sort of insight, giving the language some depth would make SO Docs standout, and be the place that is sought out when doing something new.
    – Michael B
    Commented Apr 1, 2016 at 23:21
15

Why I support documentation

I'm still supportive of Documentation. Explanation and examples are hugely important for understanding an API. As Stack Overflow currently stands, asking for a basic example for some task or API is likely to be closed or at least downvoted, even though these kind of examples would be helpful to many people. Documentation fills that void.

Complex topics

@NicolBolas talked about a kind of documentation that does not fit well into the current structure. I'm sure there are a number of complex topics that would be difficult to provide simple examples for. And maybe there needs to be some adjustment of the structure to accommodate these topics. However, I would say that for the vast majority of documentation topics, it is possible to provide several basic examples that illustrate how to do the topic in question.

The +5 Reputation for upvoted answers citing the documentation

I tend to agree with @JamesDonnelly that the +5 is not good, but not because I think people should just do it for free. Awarding reputation is helpful for soliciting more examples. This fits with the general structure of Stack Exchange. However, giving everyone who contributed a documentation topic +5 every time an answer linking to it gets upvoted is excessive. I can easily imagine 50 or 100 answers linking to a major documentation topic. If those answers are themselves high traffic, then that would translate to a huge reputation points gain every day just for contributing to a single topic. This seems a little disproportionate compared to the Stack Overflow method of gaining reputation points.

I recommend dropping the +5 and keeping the +10 for upvoted examples.

Organizational structure

I'd like to see more organizational (hierarchical) structure to the documentation, similar to how most official API documentation is laid out. This would provide an intuitive and logical way to find the topic you need. It would also naturally prevent a lot of duplicate topics.

I've written about this before, but I didn't get much response.

2
  • 6
    Let's take this answer of yours from SO for an example of the problem here. That answer would actually be multiple independent examples. And yet, the introductory paragraph (which is prose text, not an example) needs to be the very first thing that a user sees when searching for the topic of "prepared statements". But your answer is not the accepted one. So most people will see the code-dump answer first, denying them vital information about prepared statements. Docs.SO seems to promote this kind of thing, not prevent it. Commented Mar 22, 2016 at 16:07
  • 14
    "asking for a basic example for some task or API is likely to be closed or at least downvoted, even though these kind of examples would be helpful to many people. Documentation fills that void." This is nonsense, SO documentation can never be the manual. If someone is asking questions about the Windows API, you would give the canonical page on MSDN. If someone is asking questions about the Linux API, you refer to the relevant "man page". And so on. This is the problem, the SO documentation can never be canonical, it can't be the manual. Unless you suggest copy/paste whole API docs into SO..
    – Lundin
    Commented Mar 24, 2016 at 7:36

Not the answer you're looking for? Browse other questions tagged .