182

This post was inspired by the "Is Documentation failing?" question, but it's something I've been thinking about for the system.

The fact is: The idea of world-editable, world-moderated content makes sense for a Q&A site. Q&A is mostly ephemeral, with most questions not having long lasting value. If some question is badly answered it's no big deal; it will be asked again and eventually a good answer will rise up. Asking a question you're not expecting an authoritative response, you're hoping for some help. Opening it up to the world makes sense, because someone can just happen to know the answer and throw in their two cents.

Documentation is different. Documentation should be highly accurate, highly consistent, and highly informative. Documentation should be written by experts in their field. You should count on documentation being correct, not maybe correct or just an idea, or a response thrown in by someone who doesn't really understand what you're asking, like you get in Q&A all the time.

This is why Documentation has problems. You're trying to treat it exactly like Q&A, and by its very nature, it isn't. And so you have the morass that is Documentation. But that's OK, because it can be fixed. One of the first rules of startups is to be willing to throw one away. Well, let's throw this one away and start again.

Here's how the new Documentation should work:

  • Anyone can request a topic, and vote for its priority in the list of topics to write.
  • Only silver badges and higher in the corresponding tag can write/edit documentation.
  • Only gold badges and higher can approve documentation/edits. If gold badges differ, it goes by what side gets more gold badges to vote.
  • No reputation. Instead, your username gets listed as a contributor to that page, if your change is accepted.
  • Gold users can accept changes as either minor (not added to list of contributors; used for spelling mistakes and copy editing) or substantial (for anything that fixes bugs, adds code or explanations; added to list of contributors).
  • On a user's main and jobs profile, you can see a list of pages they have contributed to.

You'll get much less documentation. But the documentation you will get, will be higher average quality, more accurate, and more usable. And if you're calling it documentation, that's exactly what you want.

Yes, it's elitist. But you don't want someone who just read a high school textbook to write books on physics, you don't want to let someone who hasn't demonstrated mastery to write this.

17
  • 14
    Maybe let everyone suggest minor edits for typo or grammar fixes
    – Bergi
    Commented Dec 20, 2016 at 7:12
  • 43
    I like the criteria that only silver badges can write docs. But if the bar is set too high, I assume that this will have the same issues than more or less all open source docs are struggling with: the highly skilled and knowledable people are more concerned writing the actual thing than writing the documentation.
    – cringe
    Commented Dec 20, 2016 at 7:27
  • 7
    This looks like a knee-jerk reaction to me. Yes, there are problems as indicated in the "Is Documentation failing" discussion, but I don't believe these suggestions will fix them.
    – user247702
    Commented Dec 20, 2016 at 11:16
  • 1
    This only makes sense for the tag that are visible on this page.
    – Knu
    Commented Dec 20, 2016 at 12:20
  • See also my question Reviewing changes after the fact, where I suggest that at least a "Subject Matter Expert" (which might be, but doesn't have to be indicated by a badge in the relevant tags) should sign off on every change.
    – CodeCaster
    Commented Dec 20, 2016 at 12:33
  • 10
    "Q&A is mostly ephemeral, with most questions not having long lasting value ... If some question is badly answered it's no big deal; it will be asked again" - :( While this is an accurate description of the current state of Stack Overflow Q&A, it's not how things should be. On the other hand: "eventually a good answer will rise up" - now you've hit the major difference between the two worlds. In Q&A, bad information doesn't matter much because it can be outcompeted by good information. But docs are collaborative, not competitive; the remedy that works well for Q&A is not available.
    – Mark Amery
    Commented Dec 20, 2016 at 12:35
  • 9
    @MarkAmery I hate keeping to see that claim. I have yet to see that happen. Good answers do not rise to the top. Answers that provide copy-pasteable code do, whether that code is correct or not. See for example the classical "winforms textbox numerical input" questions, all hundreds of them, where the accepted and highest voted answer claim you should use the KeyPress event for that, which you definitely should not.
    – CodeCaster
    Commented Dec 20, 2016 at 12:39
  • 8
    @CodeCaster I will certainly grant that better answers don't always rise up to the top and have been frustrated several times by my failure to dislodge a bad answer (though I have seen this process succeed, many times - my top 6 answers all outcompeted significantly-upvoted inferior answers on old questions). But at least better answers can be posted (and so can comments point out the bad answers' flaws). That's enough to help a careful and thorough reader. Docs doesn't offer us any real ability to publicly express dissent besides editing and hoping the edit sticks around.
    – Mark Amery
    Commented Dec 20, 2016 at 12:48
  • Because there are only so many q
    – SGR
    Commented Dec 20, 2016 at 14:55
  • 2
    "world-editable, world-moderated content" Wikipedia does get it right, and not just on their protected pages. The biggest problem may be that not enough users are editing documentation in the first place, to find and fix errors promptly.
    – jpaugh
    Commented Dec 20, 2016 at 15:07
  • How about just "you have to have 5 positively-scored answers in this tag that are at least a week old" in order to contribute to Docs for a given tag?
    – TylerH
    Commented Dec 20, 2016 at 15:36
  • @TylerH: That's way too ephemeral. of a suggestion. Maybe someone had a busy week at work. Maybe they didn't get to the good questions before they were answered. Maybe they spent their SO time improving Docs rather than answering questions. It seems ridiculous to say that someone had the right to contribute one week but not the next because they didn't put in enough time in Q&A. Commented Dec 20, 2016 at 16:32
  • @NicolBolas Haha, no, I mean as a one-time minimum entry, not a new check every time someone wants to contribute.
    – TylerH
    Commented Dec 20, 2016 at 17:06
  • 3
    @TylerH: That number would have to scale depending on the tag. Anyone can easily post 5 positively-scored answers in the most popular tags given enough time, and all of a sudden it means they must know what they're talking about.
    – BoltClock Mod
    Commented Dec 20, 2016 at 17:17
  • @BoltClock True; my suggestion was geared more toward placating the "everyone should be able to edit" crowd by implementing at least a basic quality block. I personally would prefer at least a bronze badge in a tag to be able to suggest edits, a gold badge to make automatic (w/o review) edits, and a silver badge to make/commit to new tag proposals.
    – TylerH
    Commented Dec 20, 2016 at 18:51

6 Answers 6

89

"Only silver badges and higher in the corresponding tag can write/edit documentation."

This won't work for relatively low-traffic tags. Tags that have enough traffic on here to get documented, (At least 500 questions and 5 committed users.) (source) don't necessarily have any silver badge holders.
Even if there's one, you can't expect that single person to maintain the topic.
This could be an argument against documenting said tag, but then the question would be: When do we document a tag? When it has 4 silver badge owners? 5?
What if someone that works for <tag> registers? He couldn't contribute to the tag's documentation for quite some time.
Besides, I'm sure you've seen gold badge owners write gibberish. I know I have.

"Only gold badges and higher can approve documentation/edits. If gold badges differ, it goes by what side gets more gold badges to vote."

Same argument as above. This could work for high-volume tags, but not for smaller tags. Besides, why can you edit at silver, but approve only when you get gold? On Stack Overflow, the review queue, and review-less edit privileges are both granted at 2k rep.

"No rep. Instead, your username gets listed as a contributor to that page, if your change is accepted."

On large tags, your username will be drowned out in a massive list of names, removing all incentive to contribute, other than pure altruism. While this isn't necessarily "bad", this will result in even less activity in documentation than there already is.

"Gold users can accept changes as either minor (not added to list of contributors, used for spelling mistakes and copy editing) or substantial (for anything that fixes bugs, adds code or explanations. Added to list of contributors)."

This has quite some potential for abuse. I'd prefer the "Major/Minor" algorithm to be changed to count characters changed, instead of a "length" difference.

"On a user's main and jobs profile, you can see a list of pages he's a contributor to."

That's already accessible on your profile.


The point of documentation is that, while anyone can edit it, there is enough incentive / functionality available to improve / correct mistakes.

In the first few weeks, documented tags were a massive load of gibberish. While it's still far from perfect, the community did patch up most of the content. I doubt we'd have gotten this level of quality (*cough*) with the suggested rules in place, simply due to lack of activity.

24
  • 11
    Pessimism aside, I agree there is a lot to be improved about documentation. I just don't think that ((un)intentional) "Elitism" is the answer.
    – Cerbrus
    Commented Dec 20, 2016 at 7:56
  • 5
    "Tags that have enough traffic on here to get documented [...] don't necessarily have any silver badge holders." -- So there are no users we can assume are qualified to answer. One could say this is a good reason to not have any documentation on that at all. That ths is okay is the basic assumption of the OP: quality instead of quantity. That means not only less on some topics, but also fewer topics.
    – Raphael
    Commented Dec 20, 2016 at 12:21
  • 2
    "What if someone that works for <tag> registers? He couldn't contribute to the tag's documentation for quite some time." -- We could introduce "professional" badges for tags that correspond exactly to one project or company. That said, this may be a non-issue: SE never cares about actual competence but only about how much rep you've farmed. I'm pretty sure you don't want to open this can of worms here.
    – Raphael
    Commented Dec 20, 2016 at 12:23
  • 2
    I think this answer focuses too much on the tag badges that were suggested as a threshold. We do need some kind of gatekeepers per tag (multiple people), who knows what's already in there (to fight duplication), who collaboratively decide what's on-topic for the tag (to make sure the docs focus on the right thing), who know of best practices in the language or framework (to prevent bad advice), and so on. As of now, anyone who can post something that looks like code and reads like English will get their content approved.
    – CodeCaster
    Commented Dec 20, 2016 at 12:37
  • 8
    The argument that "gold badgers can write crap too" is a very weak one. Statistically speaking they are much less likely to do so, and if they do other gold badgers will fix this anyway. The point is not that silver/gold badgers are perfect, but that they have at least shown a minimum use of the tag at hand; it's not a guarantee but it's much better than absolutely nothing. This should also reduce spam on Documentation to practically zero... I doubt spammers want to spent the time and effort to achieve a silver/gold badge in order to post some spam there, that gets remove in seconds.
    – Bakuriu
    Commented Dec 20, 2016 at 13:08
  • 2
    @Bakuriu: That was meant to illustrate that a gold badge is a poor measure of someone's capability of writing good documentation.
    – Cerbrus
    Commented Dec 20, 2016 at 13:33
  • 2
    @CodeCaster: I agree that we need a threshold. I'm just explaining that gold badges aren't a suitable one.
    – Cerbrus
    Commented Dec 20, 2016 at 13:35
  • 4
    @Raphael "So there are no users we can assume are qualified to answer.", I disagree. Those low-traffic tags still have people answering questions all the time, with quality. The issue here is that there are less questions and the answers are not viewed as often and generate less upvotes. But relatively spoken I think they can easily have as many high quality answers as gold tag holders in popular tags. Commented Dec 20, 2016 at 13:57
  • Don't we have verified employees for certain companies, e.g.: Microsoft? Couldn't we do something similar for particular technologies/projects if someone wanted to fast-track into documentation? Of course, I don't know how SE verifies that in the first place...
    – canon
    Commented Dec 20, 2016 at 14:08
  • @canon: no such verification exists on SO.
    – Cerbrus
    Commented Dec 20, 2016 at 14:16
  • 1
    @GabeSechan: "Top X tags" places a limitation on who can contribute, regardless of the quality of the contributor. You'd be excluding a massive portion of SO's userbase, just because they don't happen to be specialized in one of the top X tags. For example, .NET is at position 17. It has 109 gold badge owners, at this moment.
    – Cerbrus
    Commented Dec 20, 2016 at 15:19
  • 4
    @GabeSechan: "I'd say start small and grow-" They tried that in Beta, with a curated list of participants over a small set of tags. It didn't exactly yield great results, so they just put it out there for everyone to use. Commented Dec 20, 2016 at 16:27
  • 2
    @Cerbrus Did you just verbify "strife"? Certainly seems appropriate for this topic. :-)
    – Mike M.
    Commented Dec 21, 2016 at 3:18
  • 1
    @MikeM.: Derp, that should've been a "v".
    – Cerbrus
    Commented Dec 21, 2016 at 7:25
  • 1
    "The point of documentation is that, while anyone can edit it, there is enough incentive / functionality available to improve / correct mistakes." That's the crucial point. Documentation needs to actively encourage contributions from highly qualified users more, for example by a better environment (see all the enhancement requests). Commented Jan 21, 2017 at 9:31
25

I don't think the problem of information quality is due to unknowledgeable people providing information. OK, it is. But the reason why it isn't being corrected is due to the lack of participation in Docs.SO.

Experts have abandoned it. Changing it to be "elitist" isn't going to draw them/us back. Why? Because having to clean up bad content is only one of the problems of Docs.SO.

The difficulty of categorizing information (a flat hierarchy of Tag/Topic/Example). The difficulty of making larger-scale changes. Being example-focused documentation for systems where examples aren't a good way to educate people. Not being clear on what qualifies as a "Topic". And so on.

Adding restrictions to Docs.So that only make it editable by proven experts won't help if experts don't want to use it. You first need to build a system that experts would actually be interested in using.

And right now, Docs.SO isn't that.

4
  • 8
    This pretty much sums up my opinion. If I'm knowledgeable and motivated enough to write documentation for something, I'm going to contribute to official documentation, where I have a say in its organization. If I can't do that, I'm going to write a blog post, where I have full control over its organization. I'm not going to fight Docs.SO's tooling if it gets in the way of writing clear documentation. Commented Dec 20, 2016 at 20:10
  • @JeffreyBosboom You say you would have a say in the organization of the official documentation? Cool. I want that too. What is the secret of achieving that much influence? Or do you mean Documentation here is just not flexible enough? Commented Jan 21, 2017 at 9:35
  • 2
    @Trilarion Of course, I have to convince other documentation maintainers that my changes are worthwhile, and probably volunteer to do much of the work required. By have a say, I mean that kind of negotiation is possible, not that I can dictate. But SO Docs presumes how documentation should be structured, the community's complaints here on meta are being mostly ignored, and based on the pace of Docs development I don't think the developers could change course even if they agreed. Commented Jan 21, 2017 at 19:20
  • @JeffreyBosboom I understand and also agree in general. So, given the positive feedback that the idea of example centric documentation received in the initial discussion here, it seems what we really would need to make this fly is a much more flexible design and a sense of ownership of examples, so people have a say and can coordinate among themselves how to structure the whole thing. It seems good examples are complex enough things that they cannot just be pressed into any design. Commented Jan 22, 2017 at 12:54
6

I think the general idea is very good. Documentation should be written by experts.

Silver and gold badges are awarded for a minimum number of answers with a minimum total score. That's some indication, but not ideal.

There should be a separate "proven quality" badge that qualifies for documentation. Awarded for a minimum number of answers with a minimum number of average upvotes. Maybe ignoring top and bottom outliers. There are established scientific statistical methods how to identify quality. SO should use something along that line.

Then again, I don't like the title "documentation" at all. It's a collection of examples. It's pretentious to call that "documentation". "Documentation" is a good term for what authors or maintainers of a software have to say about it - not a bunch of anonymous hackers. That should be called "examples" or "canonical answers" or something. Much has been said about that already ...

1
  • 5
    A collection of examples is often called a cookbook. That term has somewhat negative connotations, but at least it would get us all on the same page as to what we're expected to build. Commented Dec 20, 2016 at 20:12
4

I agree that documentation has its problems (as well as Q&A and everything else in this world), but elitism is not the solution. Giving extra power to trusted users is OK, but building a wall to keep people out is not.

There are many users with good will that want to help and make this project to work. We need to remove who is abusing the system by adding poor content on the quest for rep, but let's remove them based on their actions, not using prejudgments.

Also, as an example, Wikipedia is a kind of "documentation" that has many complex topics with high quality content. It works without having elitism there. Anyone can contribute and their moderation tools work pretty well to filter bad content.

The key factor is in the tools. How can we properly handle first-time contributors? How to fine tune gamification to reward good contributions and filter out who is abusing the system? Let's continue to work on documentation and focus the discussion on the moderation tools, not about who is contributing.

8
  • 1
    Why isn't it? If you want documentation- high quality, authoritative, trustworthy- you will never get that by letting everyone add it. Please don't say wikipedia- they turned from crap into something approaching good as they added more layers that made it harder to edit. Go ahead and try to edit the Trump page- you won't be able to. Because they're elitist and won't let you. Commented Dec 20, 2016 at 14:52
  • 4
    @GabeSechan Wikipedia's quality is not exclusively limited to pages which are locked! Nearly every computer science page I look at is reasonably accurate, despite being open to edit by anyone who is interested. That's about as much as you can say for real-world documentation, too! Even a company's own documentation is often inaccurate, and who could represent a better expert?
    – jpaugh
    Commented Dec 20, 2016 at 15:01
  • 1
    @jpaugh You obviously weren't around and editing wikipedia for most of its time. It started out pure crap. It wasn't until they added admins and cliques formed spending all their time reverting bad (and frequently outright malicious) changes that they moved from crap to decent. The world editable part made them take off in terms of quantity of content, but only when they became more restrictive of what could be added did they increase quantity. Not to mention the dozens of other attempts they made to spread to other sites that failed. Commented Dec 20, 2016 at 15:11
  • 1
    @jpaugh In other words- just because something managed to strike lightning in a bottle once doesn't mean it will again. Or that it was the best way of doing things in the first place. Commented Dec 20, 2016 at 15:12
  • 4
    @GabeSechan: But Wikipedia never out-right prevented people from editing, except for page locks. Yes, they have legions of people who make it their personal business to weed out crap. But that's filtering after the fact, which is different from being "restrictive", from preventing someone from making an edit at all. Commented Dec 20, 2016 at 16:23
  • @GabeSechan Wikipedia can be seen as a case study in how this form of open documentation should be designed. If anyone is allowed to edit, there needs to be, as a bare minimum, 1) a group of moderators & administrators, plus other users willing to expend extra effort to verify edits and revert any bad ones that get past them, 2) a full suite of tools that facilitate doing this, 3) the ability to selectively ban users that repeatedly make bad or malicious edits, and 4) the ability to selectively lock pages that are frequently vandalised and/or edited with incorrect information. Commented Mar 1, 2017 at 20:26
  • @JustinTime there's a poker term called "results oriented thinking". Basically id's when you see something happen once or twice due to luck and ignore the probabilities. Claiming Wikipedia's success proves your model is the epitome of results oriented thinking. No other attempt to do something like that had ever worked well, and most attempts like phps documenting are reviled. Commented Mar 1, 2017 at 21:07
  • @GabeSechan I didn't say that Wikipedia proves that this form of documentation is always a success. I said that Wikipedia implemented it successfully where others did not, and thus that attempts to implement successful documentation should style themselves more after Wikipedia than after any of the attempts that failed, to hopefully engineer an environment more conducive to success. Basically, if we're going to imitate someone, we should imitate the one that got it right instead of the ones that got it wrong. Commented Mar 17, 2017 at 20:08
4

Your question reminds me of The Cathedral and the Bazaar:

Who would have thought even five years ago (1991) that a world-class operating system could coalesce as if by magic out of part-time hacking by several thousand developers scattered all over the planet, connected only by the tenuous strands of the Internet?

This sounds very much to me what I might say about Stack Overflow's Q&A system. It's certainly true many questions are disposable (and, in fact, disposed). And, of course, most askers are more interested in getting some help with whatever is blocking their progress (even if the advice might be a bit flawed) than with increasing the total sum of human knowledge. But strangely, almost miraculously, many answers on Stack Overflow are "highly accurate, highly consistent, and highly informative". There's even a reliable way to find them: questions with many votes and lots of pageviews tend to have the best answers.

If you are anything like me, answers on Stack Overflow have become de facto documentation. I mean, when writing a Transact-SQL query and there's a function I've forgotten how to use or know must exist, but don't know the name, I go to Google, not TechNet. When a Stack Overflow result turns up, I generally chose it because I know that in addition to a reminder of the syntax (I'm looking at you, date conversion), there will be a bit of working code. And if the first answer doesn't work for me, there's almost always another that does.

Unlike, say, surgery, a lot of programming expertise comes from trial and error. Having a computer science degree can really help, but it's no substitute for spending a week with a debugger or discovering your code doesn't doesn't scale in production. Most documentation tells you how the technology was designed to work. It rarely explains the tricks that make it actually work in less-than-ideal cases. Nor does it usually call out clever hacks that work around design flaws. And sometimes the tricks of the trade change over the life of language or library.

I don't think there's a vast, untapped resource of experts waiting for some reason to write excellent documentation. I mentioned elsewhere that the success criteria for Documentation next year is whether we can increase the number of users. Obviously, we aren't going to narrow our potential field of users to an elite few. But if we did, how could we create anything different than what already exists? If Documentation is to fail, wouldn't it be better to fail differently? Doesn't it make sense to try out the bazaar model to see if it'll improve upon the various cathedrals we've been using all these years.


Cody Gray astutely noted that if Q&A already works as Documentation, there's perhaps no reason for a separate product. A few years ago, Joel Spolsky suggested pushing for something like Q&A as documentation. In particular, he suggested:

  1. Editing questions to be more general and
  2. Creating more canonical answers.

While some people have done this (and always have), it violates two norms the community have generally accepted:

  1. Don't ask questions that are "too easy" and
  2. Don't make drastic edits to other people's posts.

Alternatively, you can avoid those pitfalls by writing self-answered questions. In my experience, that's yet another activity looked on with suspicion. So it's possible to make the idea work (if you are particularly expert in Q&A), but it's far from easy. For better or worse, you have to fight with the design of questions and answers.

So we designed Documentation with a reputation system that encourages collaboration, reviews for most contributions, a versioning system, robust links and so on. We believe that part of writing social software is creating affordance for desirable behavior. Even so, the most likely failure case for Documentation, in my opinion, is that answers continue to be more useful than content intended to be canonical.

10
  • 6
    And the cathedral won. Almost no major open source projects are actually bazaars anymore- the majority of contributors to all of them are paid for by various corporations to work on the project. Commented Dec 21, 2016 at 5:25
  • In the meantime- you're doing the exact opposite. People who are experts in the various areas take a look at the utter shit that is documentation, and run the other way. Right now I wouldn't write for it if you paid me to. I'm not saying my suggestion has all the answers, but what you're doing right now isn't working. Commented Dec 21, 2016 at 5:28
  • @GabeSechan: You seem to have interpreted ESR's ideas rather differently than I do. The distinction between bazaars and cathedrals is entirely about how they are managed, not how the contributors are compensated. The fact that many of these projects have contributors employed by different companies demonstrates they are anything by cathedrals. In any case, you can't deny that Linux and other early-90s open source project did succeed by organizing many good programmers rather than a small number of experts.
    – Jon Ericson Staff
    Commented Dec 21, 2016 at 5:32
  • 4
    "good programmers" As opposed to inexperienced ones who have no idea what they're doing and are just throwing their hat in for the fake Internet points, yes.
    – BoltClock Mod
    Commented Dec 21, 2016 at 5:34
  • 3
    "Most documentation tells you how the technology was designed to work. It rarely explains the tricks that make it actually work in less-than-ideal cases. Nor does it usually call out clever hacks that work around design flaws. And sometimes the tricks of the trade change over the life of language or library." I think what we really need is a way to convey this effectively to everyone (at least, everyone in the target audience). Right now, for whatever reason, none of the attempts at telling people what Documentation is and how it's supposed to work have managed to get it across.
    – BoltClock Mod
    Commented Dec 21, 2016 at 5:34
  • 3
    I don't really understand how the Cathedral vs. Bazaar analogy applies here. It would only make sense if Stack Overflow Q&A was the cathedral, but it clearly is not, and the rest of your answer seems to agree with me on that point. As such, we already are trying out the bazaar model, and it has been quite successful. So successful, in fact, that "answers on Stack Overflow have become de facto documentation". Which brings us back to the recurring question, why do we need a special place for this. But I guess you weren't trying to answer that this time.
    – Cody Gray Mod
    Commented Dec 21, 2016 at 5:35
  • @CodyGray: Stack Overflow is the bazaar model. The OP is suggesting converting Documentation to a cathedral. You are correct I did feel it best to answer the question asked. Joel did push for the concept of canonical answers. Unfortunately, it's getting harder and harder to ask the sorts of questions that might result in useful documentation. It's also, you know, a mighty big hack. To take a very basic problem, what should you do when the canonical answer changes?
    – Jon Ericson Staff
    Commented Dec 21, 2016 at 5:45
  • 3
    "Most documentation tells you how the technology was designed to work. It rarely explains the tricks that make it actually work in less-than-ideal cases." I think this goes back to user expectations. When people see the word "documentation", they do not think of something that "explains the tricks...". They think of reference manuals, something that is both explicit and comprehensive. Books that teach you tricks aren't called documentation. They're called "cookbooks". If that's what Docs.SO should be, then the reason people are using it wrong is because you named it incorrectly. Commented Dec 21, 2016 at 5:57
  • 2
    "Unfortunately, it's getting harder and harder to ask the sorts of questions that might result in useful documentation." Um, why is it getting harder? Because most of the good canonical questions have already been asked? Then the problem has been solved. If it's because people are closing legitimate questions, then perhaps that is the real problem you should be solving? "It's also, you know, a mighty big hack. Well, I guess this is where we profoundly disagree. I don't think asking a question and getting a good canonical answer is a hack at all.
    – Cody Gray Mod
    Commented Dec 21, 2016 at 6:06
  • 3
    In fact, I strive to always provide canonical answers, even when answering what is ostensibly a narrowly-scoped question, since our stated goal is and has always been to be a resource to the larger programming community, not just a help desk. "To take a very basic problem, what should you do when the canonical answer changes?" Not seeing the problem here. When the answer changes, you either update it (if it's a minor change), or you add a new answer (if it's a major change, and you don't want to lose the old information). We support edits and new answers quite well.
    – Cody Gray Mod
    Commented Dec 21, 2016 at 6:07
-2

While I agree with your request in general, there's one bullet that simply doesn't make sense to me:

Only silver badges and higher in the corresponding tag can write/edit documentation

Why restrict improving things to such a small subset of avid SO users? Not everyone who is an actual expert on ${thing} has a badge, therefore not everyone who lacks a badge is incapable of writing good, accurate documentation about ${thing}.

It's better to let those without a badge in submit edit suggestions to ${thing}'s Documentation, which then get reviewed by those who proved their ${thing} expertise with a badge.

3
  • 1
    This is a catch-22; you have experts who aren't identified as such on Stack Overflow - and yes this community exists - but the system being used to vet those experts is on Stack Overflow.
    – Makoto
    Commented Dec 20, 2016 at 19:11
  • 1
    @Makoto I don't think it's so hard to make a sliding scale so that users in smaller tags get Docs privileges on those tags.
    – Frank
    Commented Dec 20, 2016 at 19:47
  • 1
    I agree with this answer. The question basically assumes SO Q&A is a pre-heater of Documentation. First you prove yourself on Q&A, then you do Documentation. That is probably a waste of effort. Better to separate Documentation from Q&A and judge contributors to Documentation by what good Documentation they deliver. Commented Jan 21, 2017 at 9:39

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