140

I've been raising this question occasionally in comments for a while now, but I thought it was worth asking it as a Meta question: just what's the point of Documentation? What niche do the development team intend it to fill? How do they envisage a reader using it?

Let's consider some existing sources of information for programmers, and the role they fill. Stack Overflow Q&A helps people get information they need in two simple ways that we clearly understand, and has done since its inception:

  • People can ask questions about real problems they have and receive answers, immediately helping the asker
  • So long as questions are generic enough and their titles are clear enough, people with problems can easily Google them and find the answer to their exact problem

You can of course argue about which of these mechanisms is more important and fundamental to how Stack Overflow operates (correct answer: it's the second! it's the second!), but I think we're all pretty clear that they're both there and that they both broadly work.

Of course, Stack Overflow Q&A has several innate weaknesses:

  • Since any old idiot can write or vote on an answer, without needing to be affiliated with the language or library they're writing about, a reader never has any real guarantee that what they're reading is or ever was accurate (unless the answerer thoroughly evidences his claims by showing the results of experiments or by referencing a more reliable source)
  • Since nobody is responsible for "maintaining" Stack Overflow answers, even answers that were once accurate may be obsolete by the time a reader arrives
  • While there are many "How do I do X?" questions on Stack Overflow, there are few "What does function X do?" questions - it's a powerful tool for doing a task -> function lookup, but not a useful one for looking up how a function behaves

Let's consider other sources of knowledge. What's official documentation (with a small 'd') useful for? How does it help readers? Well, I can think of a few ways:

  • Since it's "official" (i.e. written by the people who wrote the code, or those close to them), the vast majority of information is likely to be accurate down to the most pedantic detail. This makes it useful either for a reader who wants certainty about how something will behave, or a reader who wants to cite a reliable source elsewhere (like in a Stack Overflow answer)
  • It provides an easy and fast mechanism for looking up how a particular API behaves (and typically documentation on a particular API can be immediately found by e.g. Googling for the function name)
  • It provides a way to browse and explore the capabilities of a language, tool or library, in order to build up a comprehensive understanding of what it can do

But offical docs also have deficiencies that prevent them from being the One True Source of Knowledge for Programmers:

  • Not all tools have them (or else they may have been hastily written by somebody with a poor grasp of English)
  • Since information in documentation is usually structured on a per-API basis (rather than a per-problem basis like on Stack Overflow), if you're in a hurry and don't have time to read an entire manual then you usually need to know the name of the function/class/endpoint/operator you're looking for in order to search for information about it - searching for the task you're trying to perform or the error you're encountering frequently won't return useful results

So, we've got two information sources already out there with their own innate merits and weaknesses. How about Documentation (with a big "D" this time)? What are it's strengths? What are its weaknesses?

Well, I can certainly articulate some weaknesses - since Documentation has all the major weaknesses I just listed of both Q&A and official docs - the two sources of information that I make the most use of in my professional life:

  • Any idiot can write it and vote on it; there's no guarantee of quality or accuracy
  • There's no guarantee of maintenance; information may be obsolete
  • Since it's example-based, you can't look up a function and read a detailed description of its behavior
  • Plenty of stuff just isn't Documented
  • It's close to completely unsearchable. I've never seen Documentation in my Google search results, and the internal search is very poor.

I've tried, sincerely, to find a way to make use of Documentation, but I just can't see how. Recently I learned about Python's async/await syntax. Let's compare my experience using the channels I'm comfortable with, versus what I would have experienced if I'd tried to use Documentation, and reveal some of the ways that it sucks in the process:

The non-Documentation way

  • I Google async await python via my URL bar
  • I open some relevant docs that come up as the first result in a new tab
  • I open a lengthy blog post explaining the concept and start skimming. The blog post quickly explains that asyncio is "an event loop framework which allowed for asynchronous programming" - cool, I roughly know what that means - and gives me a rough explanation of what a "coroutine" is. Okay, that's cool.
  • I change tab and have a look at what the docs say. They're not great introductory docs, but sweet, there are some examples I can copy and paste showing the usage of the async and await keywords. They're kind of bad examples, though; they don't show any sort of concurrency, there's only ever one of these "coroutine" thingummies in play at a time. How do I run coroutines in parallel?
  • I Google asyncio wait for multiple coroutines
  • The top three results are Stack Overflow questions pointing me to the wait(), ensure_future() and as_completed() functions. Boom, that's enough for me to start writing something useful, and I can learn more as I go.

Plenty has gone imperfectly in this process. I wasn't sure what resource to initially start reading. Both sources I picked had a lot of waffle that I didn't really have the patience to read through when I'm just trying to 1) get a basic gist of what the heck's going on and 2) figure out if the source itself is useful to me. The official docs had crap examples that failed to illustrate the fundamentals of the feature I was reading about, so I had to bounce between different sources. Can Documentation do better?

The Documentation way

Since Google doesn't return Documentation results, let's go there manually:

  • I go to https://stackoverflow.com via my URL bar's autocomplete
  • I click "Documentation"
  • I click "Python Language"
  • I CTRL-F for "async". There are no results.
  • Wait, there are 9 pages of topics? No wonder CTRL-F didn't work. Let's use the search function.
  • I search for async await. The top result is something (presumably irrelevant, going by the information displayed to me) about websockets - WTF? At the bottom of the results there's something about "Asynchronous Executors", though - that sounds related! I open that.
  • It sucks - the Example uses concepts like "asyncio" and "executors" without explanation even though this is my first time encountering them, and then gives me a useless "Hello, World!" example that doesn't show me how to run anything in parallel. But at least I've now stumbled onto the asyncio module topic, which didn't show up in my search results
  • The Example at the top of the page actually contains (in its third code block, after some confusing examples that tell me to do "time intensive stuff" inside async deffed functions) a reasonable example of how asyncio can be used. Unfortunately, if I were really a beginner arriving here, I wouldn't have the basic grasp of what the feature I was reading about was to be able to recognize that or understand what was going on - and that's it. That's all Documentation has to offer. At this point I'd need to give up and use Google; the entire process of using Documentation here was a waste of time.

The non-Documentation path to wisdom was a little bumpy and it's possible to imagine a shorter route, but at least I got there. Using Documentation was also a slow and bumpy process - it took me 4 page loads to even see some search results, heaven's sake, compared to 1 when I Google via my URL bar - and in the end, the information I needed simply wasn't available in Documentation. There were only unexplained "Examples" that couldn't possibly make sense unless I read another source of information (which would likely contain similar examples anyway, because, y'know, Stack Overflow answers and official docs generally contain examples - just with sufficient context and explanation to be able to understand them, unlike the random code dumps I found in Documentation).


And so I return to my original question: what's Documentation for? How am I supposed to use it, as a reader who is seeking information? In what circumstances would I benefit from Documentation existing, given that I already know how to use official docs, Stack Overflow Q&A, and Google? What are its strengths, relative to little-"d" documentation or Stack Overflow's existing Q&A? What's the envisaged user story that somehow involves me ending up reading a piece of Documentation and finding the information that I needed?

At the moment, it seems very clear to me - and most of the community - that Documentation is inferior to other existing sources in every way, to the point that it might as well not exist. If that's going to change, the users authoring it need to be given some clear vision of who is going to use it, and how, and what characteristics a Topic or Example needs to have to serve those ultimate use cases. Until then, you're just going to be stuck with the mess you have now - a collection of contextless code dumps, upvoted by other people contributing contextless code dumps, all entirely useless to anybody.

5
  • 47
    Thank you for taking the time to articulate what I've been wondering for a while now.
    – Whymarrh
    Commented Feb 14, 2017 at 2:02
  • 22
    "I've never seen Documentation in my Google search results" I think this is actually intentional, presumably for while it's 'Beta'.
    – jscs
    Commented Feb 14, 2017 at 2:39
  • "How am I supposed to use it, as a reader who is seeking information?" Reading it maybe? But I guess the designers wanted you to use search or I guess that's why they didn't implement some sort of topic order. So I guess you used it exactly the way it was supposed to be used. Commented Feb 14, 2017 at 11:49
  • 1
    To be fair, the four page loads it took to get to docs would have been shorter if you'd typed "stackoverflow.com/documentation" instead. I agree, though; the process is a lot more confusing on SO Docs than most official documentation.
    – Nic
    Commented Feb 14, 2017 at 19:37
  • 2
    The worst part is: after you land on the Example, the example shouldn't tell you what asyncio is -- that belongs in the Introduction and Remarks sections at the top and bottom of the page, which no reader would naturally navigate to.
    – Frank
    Commented Feb 14, 2017 at 20:48

5 Answers 5

8

You are drawing out two interrelated problems:

  1. It's hard to figure out who the audience is.
  2. The audience can't actually find Documentation.

Clearly the second is an easier problem. We've thought about the various ways we can increase exposure to Documentation and haven't implemented any of them yet. Until the release of the discussion tab we haven't had a system that is sufficient to create great content. (And the jury is still out about that.) So it doesn't make a lot of sense to push discoverability too hard. But that's about to change as we are now planning ways to index Examples in our internal search and add relevant links to sidebar of questions.

When we get more people reading Documentation, we'll be testing our hypothesis that example-driven documentation fills a niche. In particular, we aren't interested in official (though we've had a lot of companies ask about it) or comprehensive documentation. Maybe we'll come back to that idea, but we're focused on transforming the state of the art rather than making incremental improvements. (Have we mentioned failure is always an option?)

Instead, we want to create something that looks a little closer to Stack Overflow answers, which often serve as a defacto manual:

Essential Copying and Pasting From Stack Overflow

A few years ago, Joel suggested we create canonical answers through editing. It happens sometimes, but more often a Google search will turn up weirdly specific code. And unless someone happens to provide a new answer, it's unlikely many canonical questions will be updated. Plus, even if you could solve those problems, there would still be a necessary, vestigial question between readers and the answers they seek.

So we want to create a system for answers to really broad questions that doesn't require the actual question. You've hit upon the weak spot of the plan, however. Askers provide a necessary service by being a representative of the audience for our library of answers. They can provide useful feedback when an answer isn't clear or when it fails to address the real point of confusion.

So here's the gamble we are making: as we expose more people to Documentation, some segment of that audience will be skilled in writing examples that illustrate various language features. Those folks will identify ways existing Topics can be improved and propose changes that make the content more useful. Those people don't have to be attached to the team that designed the language or even be an expert in all the minutia. Instead, Documentation contributors need to be skilled at demonstrating language features with a bit of code and a bit of prose. Those folks are out there. Some of them have already found Documentation and are contributing.


The Asyncio Module topic you brought up is not too far from what I look for in Documentation. Critically, it's not a great tool for learning the concepts from scratch. As far as I'm concerned, it's perfectly fine if people start with a class or a tutorial or the official documentation or lore passed down from coworkers. However it is you first learn about concepts like coroutines (I learned about them reading the Lua manual), there's going to be a point in the future where a gentle reminder of how they work can be helpful. That's where we hope Documentation will shine.

18
  • 1
    I think you're (importantly) right to say that points 1 and 2 are interrelated. On Q&A, our audience is dictated by how they find the content. A reductive definition of Q&A's primary audience is "people who Googled something and clicked on this question's title in their search results" - and it turns out that that's actually sufficient information to understand a great deal about what sorts of people those readers are and what content they want to find. We don't even have such a reductive description of the readers of Documentation yet - so who are we meant to write for?
    – Mark Amery
    Commented Feb 14, 2017 at 13:01
  • 21
    While it may be tongue-in-cheek, it very much concerns me that you use the "Copying and Pasting from Stack Overflow" cover art in an answer attempting to justify Documentation. Do we really need to encourage more people to copy and paste code from the Internet? This is a common objection to Stack Overflow, but the reason I think it is invalid is because good Q&A offers explanation, enough so that you aren't just cargo-culting and introducing a mélange of security and other bugs. You are risking Documentation lacking the crucial explanation part, turning into the worst of code-only Q&A.
    – Cody Gray Mod
    Commented Feb 14, 2017 at 14:06
  • 1
    Of course you've had a lot of companies asking about using Documentation for official documentation. They already use Q&A to outsource tech support, now they can outsource documentation... Commented Feb 14, 2017 at 16:01
  • @Cody: Are you saying that people read past a wall of text to get at the one interesting nugget they are looking for? Say it ain't so! Anyway, that's a very romanticized view of answers. In my experience the accepted answer is often a naked or scantily-clad code block. If there are other answers, they might go into more detail, but who knows if anyone reads them. Meanwhile, we explicitly recommend adding prose to Examples and it's potentially not a waste of time to do so since there aren't many duplicate Topics. Plus it's easier (and rewarding) to edit in explanations where needed.
    – Jon Ericson Staff
    Commented Feb 14, 2017 at 17:38
  • 3
    @JonEricson "Anyway, that's a very romanticized view of answers [...]" -- Perhaps I am reading too much into your comment, but that sounds worryingly like a suggestion to give up on having Q&As that are more than a source of snippets for copy-pasting, and instead redirecting all eforts towards creating creating content which is not too localised and has long-term value to Documentation.
    – duplode
    Commented Feb 14, 2017 at 18:54
  • 3
    @duplode: No. I'm saying we'd really like it if people were to write detailed and full answers that covered the general and not just the specific case. But people don't do that for a variety of reasons. Documentation tries to address some of those reasons. But if you want to ignore it and focus on great answers, we're overjoyed you've found something you like doing with our site. If we had more of you, there'd be no need for something like Documentation.
    – Jon Ericson Staff
    Commented Feb 14, 2017 at 19:53
  • 14
    @JonEricson: "In particular, we aren't interested in official or comprehensive documentation." Then why do you call it "documentation"? People assume that something called "documentation" is intended to be at least somewhat comprehensive. Seriously, it's like SE picked the most misleading names for vital aspects of Docs.SO's design. "Topics" are meant to be question-like things in your analogy, which is very much not what the word "topic" means. And "documentation" is not meant to be what anyone thinks of when they see the word "documentation". Commented Feb 14, 2017 at 20:03
  • 2
    @JonEricson While I intend to carry on doing just that, this does sound like an admission that, by doing so, I will be swimming against an unstoppable tide. I also wonder about the potential implications of such an attitude to community moderation, beyond the individual contributor, me-and-my-answers level.
    – duplode
    Commented Feb 14, 2017 at 20:26
  • 3
    Whenever I read something like this explaining what Documentation is, it always makes me wonder if the confusion is simply because it's called Documentation... which, you know, already means something else ie what people are comparing it to
    – aw04
    Commented Feb 14, 2017 at 20:38
  • 5
    some segment of that audience will be skilled in writing examples that illustrate various language features If I may say so myself, I am in that segment. But the things I am knowledgeable about are well-covered by official documentation (indeed, that's often how I became knowledgeable about them!), and I see no reason to duplicate that information. The gamification elements of Docs seem designed to encourage that kind of duplication, with no real concern for quality. I see no point in reinventing the wheel, and then defending my new wheel from low-quality "contributions". Commented Feb 14, 2017 at 22:49
  • 1
    @JeffreyBosboom: If official documentation works for you, that's fine. We certainly don't want duplication. But I'd suggest that official documentation doesn't work for everyone. And even the best documentation has blind spots. If you happen to have the same blind spots, I can certainly understand having no use for alternatives. But that doesn't mean alternatives are without value.
    – Jon Ericson Staff
    Commented Feb 14, 2017 at 23:06
  • @JonEricson that's a really bleak view to have...personally I hope the answers I contribute try to be detailed and explain any code that is posted. Maybe the problem is more that SO isn't selective enough with who it allows to contribute?
    – user692942
    Commented Feb 14, 2017 at 23:08
  • 15
    If I may try to pithily summarise the grand vision of Documentation presented in this answer, I'd say that it seems to be "canonical Q&A, without the Q". But that leads me to immediately ask some questions, like "What's harmful about the Q?" and "How do I find the A without having a Q to Google for?" and "Can't all of this be achieved just as well (or better) with judicious self-answers?" I fear that you're trying to solve the cultural problem of not enough people posting canonical answers by creating an entirely new product that's not actually any better for creating such answers.
    – Mark Amery
    Commented Feb 14, 2017 at 23:13
  • 6
    If the goal of Docs.SO is to be a repository for canonical Q&A, then 1) you have explained this concept so poorly that it has literally taken a year before this was made clear. 2) The ill-defined notion of "topic" makes it essentially impossible for you to be able to achieve this idea with Docs.SO. 3) You don't seem to understand that the key to a good canonical Q&A is a good question. Good questions produce good answers. If you want to build a system for generating canonical Q&As, then you need to curate the construction of good questions. Commented Feb 17, 2017 at 3:42
  • 5
    @JonEricson: There is a big difference between "A topic is a canonical question" and "Topics are broader in scope than Questions". The former is a very specific concept that still remains in the realm of Q&A-questions. The latter is a nebulous area well beyond the realm of Q&A questions due to being excessively broad. Commented Feb 17, 2017 at 7:43
60

This issue largely explains why I have stayed away from Documentation up to this point. From what I have seen of it, Documentation is not...

  1. ... official documentation, because it is not official; nor
  2. ... a collection of free-flowing, internally coherent guides, tutorials or blog posts, as the format and the collaboration dynamics don't favour that; nor
  3. ... a code-only repository of examples, as the format isn't strict enough, and probably also because that would call for a rather different supporting infrastructure.

It is no man's land.

From my (admittedly far removed) vantage point, I believe it would be an improvement if Documentation moved towards a more clearly defined format. From the three ones I mentioned, which aren't of course the only ones, #1 is not an option. A natural transition towards #2 doesn't seem impossible -- for instance, if the improved "discussion" feature catches on and groups of core contributors use it to take editorial control across the various tags. #3 might perhaps be a more interesting experiment, but I suspect it would be too much of a sea change to be put into practice at this stage.

6
  • 11
    "a code-only repository of examples, as the format isn't strict enough, and probably also because that would call for a rather different supporting infrastructure." It would also require not being called "documentation". Commented Feb 14, 2017 at 2:17
  • 3
    @NicolBolas ...which is surely also part of the problem.
    – duplode
    Commented Feb 14, 2017 at 2:19
  • 26
    It is no man's land That's exactly it. When I happen to find myself on the Documentation, I just feel like I got lost and left Stack Overflow.
    – Right leg
    Commented Feb 14, 2017 at 2:24
  • Probably it's something between your points 1-3. A repository of examples and guides that may replace official documentation in case it's lacking. Commented Feb 14, 2017 at 11:46
  • @Trilarion The question, basically, is whether Documentation can play all three roles well at the same time.
    – duplode
    Commented Feb 14, 2017 at 18:56
  • @duplode I don't know if it can. The infrastructure seems to be less than optimal but then it will never be optimal. My idea for the focus: guides as a sequence of consecutive examples. Commented Feb 14, 2017 at 20:49
48

It's simply an attempt to fix the failed mission of Stack Overflow.

This site was designed to be the authoritative source of knowledge, but turned to be an endless conveyor belt with "fix my code" questions.

So, the goal of Documentation project is to make Stack Overflow great again to make it achieve its initial goal.

You cannot deny the fact that Stack Overflow participants are focused on fixing particular problems for the certain posters. Which makes answers way too localized and essentially un-reusable. I declare this as a person that searches for duplicates a lot.

While Docs are imagined to be focused on the generalized solutions. Will they succeed this time - is a question.

14
  • "[...] but turned to be an endless conveyor belt with "fix my code" questions." Can you provide evidence that this is the case? AFAIK this is factually incorrect. Commented Feb 14, 2017 at 11:32
  • 25
    Here you are Commented Feb 14, 2017 at 11:36
  • 14
    @J.C.Leitão: I can't be arsed to provide evidence but I can certainly lend a big fat "I agree" to the statement Commented Feb 14, 2017 at 12:30
  • You seem to be frustrated over not having the power to do any substantial action that can get SO's quality back on track. Could you nominate yourself at the next moderator election so that you at least have a chance to get that power? Commented Feb 14, 2017 at 14:31
  • 13
    @dorukayhan JFYI: moderators have no power for changes at all, and, in fact, are most frustrated members of this educated society. As of your speculations, they are simply wrong. Although I am indeed frustrated over many things here, this answer is but a bare and obvious fact. Commented Feb 14, 2017 at 15:04
  • 4
    Also, regarding your second paragraph: Isn't SO an authoritative knowledge source and a conveyor belt of debugging questions at the same time? There's a set of highly viewed and duplicated questions that literally dominate Google - I think this set of questions is big enough that it makes SO authoritative. Commented Feb 14, 2017 at 15:30
  • 5
    @dorukayhan Yes, there are a few that have become points of reference, though I don't know if I'd call them authoritative. The point (as I see it) is that there is a vast quantity of dupe-worthy content that is not being collected into authoritative canonical Q&As because the site is being flooded, and dupe searching is a serious chore. That's my experience in the R tag, and I suspect other tags are significantly worse.
    – Frank
    Commented Feb 14, 2017 at 19:07
  • 5
    @Frank Yes, exactly. I'd only say that it's mostly because the site doesn't (or, rather, didn't, in the pre-Documentation era) encourage such a collecting at all. And at the same time - quick on-site answers are rewarded most by the gamification system. So you just cannot expect any compilation efforts from a participant. Commented Feb 14, 2017 at 19:37
  • 2
    Note that Jon Ericson's answer and the comments to it are direct evidence in support of the interpretation @YourCommonSense is proposing here.
    – duplode
    Commented Feb 14, 2017 at 20:18
  • 7
    This is pretty accurate. See also
    – Shog9
    Commented Feb 14, 2017 at 20:48
  • I have wanted to post a meta question requesting the outlawing of debugging style questions for a while now, but I can't bring myself to do it.
    – user4639281
    Commented Feb 14, 2017 at 22:09
  • 2
    @TinyGiant that's simply impossible. There is no mechanism to enforce such a rule even if it would be approved. Commented Feb 14, 2017 at 22:39
  • @YourCommonSense sure there is, we just replace the current debugging close reason (No MCVE) with a new reason ("Debugging questions are no longer allowed") and start voting to close all debugging questions with that reason.
    – user4639281
    Commented Feb 15, 2017 at 0:08
  • 6
    @TinyGiant no, no. That's not about written rules at all. Only few are following them anyway. There are much more powerful forces: the gamification and the habit. That's not about what a law is, but how to enforce it. And you lost this battle already. Take, for example, duplicated questions: you have this reason all right, but does it change anything? Few Don Quixotes are fighting windmills, while the rest of the population is happily gains rep answering them. Gamification is a much more powerful force than one might think. Commented Feb 15, 2017 at 5:15
36

How am I supposed to use it, as a reader who is seeking information?

This has been recognized (by at least myself, but I'm sure others have said similar things) as one of the flaws in example-focused documentation.

Your example is about async/await. This is a complex feature, and merely showing people working examples that use it are insufficient to actually explain the feature. That is best done via Tutorial or even better Conceptual (blog-post/wiki/etc)-style documentation.

But that's not how Docs.SO works. As such, Docs.SO works best for constructs whose use is reasonably obvious by example. But really, Docs.SO is at its most effective for tasks of things. That is, rather than trying to document the language/library, you show examples of how to do a wide variety of things using the language/library. The idea (presumably) being that some set of that will also teach the reader the specifics of how those tools work.

Just look at the developer's ideas of what a good use of Docs.SO looks like. You couldn't read that and say that you've learned Bosun. So clearly being comprehensive and in-depth is not the point of Docs.SO (or if it is, it really fails at it).

You should not go to Docs.SO expecting to get a grounding in the specific behavior of some subsystem. You should go there when seeking information about how to use a system to do some activity. That's what examples are good at conveying, and that's what Docs.SO as a system is best and handling. To be more concrete, if you want to know what an OpenGL shader is, you go to the OpenGL Wiki page. If you want to know how to load a shader, you go to... well, also the OpenGL Wiki, but Docs.SO has some examples too.

Of course, the fact that most editors of Docs.SO are trying to turn it into a comprehensive collection of information rather than a collection of tasks to perform makes this a non-trivial problem.

1
  • 9
    From this point of view, it is interesting to consider the discussions about using Documentation entries as dupe targets, or moving canonicals to Documentation. If Documentation were strictly focused on examples, the references would flow the other way: readers would be expected look for, or be directed to, additional reading -- such as Stack Overflow Q&As -- in order to further their understanding of the example code.
    – duplode
    Commented Feb 14, 2017 at 2:51
9

Yay, another "What's this actually for?" question. Let me share my current views.

Documentation, in my opinion, at the moment lacks at least authority, consistency, quality and content.

If you want to collaboratively write something great, you need a gatekeeper: a dedicated (group of) person(s) who share the same views and vision, evaluate every modification and aren't afraid to say "no" to a suggestion.

That's not how the current Documentation works, which causes it to lack consistency and quality. People who know nothing about a subject can vote for its content, and approve modifications made by others. Anyone can propose any change they want. Almost any change gets accepted.

Now for relevant, thorough content that's actually useful for others and not only fun to write, you need people with real-world experience of the usage of a library or framework, who can write in proper English and who can think of multiple approaches to the same problem.

How to fix it?

What Q&A shows, is that there are too many "loose cannons" out there to initially outright trust anyone to modify something that important as Documentation, which is supposed to be qualitative, exhaustive, canonical content to be read by everyone. This principle needs to be reversed.

Sure, anyone can post suggestions, but only after a tag- or topic-specific "moderator", who can veto any change, approves such people's changes they can continue to provide improvements.

And of course there are "niche tags for which this is going to prove a problem", an excuse thrown in at every suggested change to the way Documentation works, but let's solve real problems first, one at a time.

5
  • I strongly disagree with your view. While I (obviously) agree on the loose cannons, I think the more people the better. What is lacking are guidelines. It works the same on Q&A, wikipedia, or wherever: the more people, as long as they're guided and told what to expect/aim for, will produce a better, more refined collaborative effort. With no target audience, no actual users, and no real guidelines, Documentation does not do that.
    – Cimbali
    Commented Feb 14, 2017 at 14:37
  • 7
    @Cimbali you're free to disagree. However, "guidelines" are doomed to fail if you have no way to enforce them. If user X thinks they've made a valid edit, and user Y and Z approve that edit, but neither has followed any guideline, then what? Start yet another rollback process? There is no lack of people willing to type documentation. There is a lack of people who can write well and in a structured manner, and if their work keeps getting undone within hours because someone else made yet another "handy addition" to what they wrote, they stay away.
    – CodeCaster
    Commented Feb 14, 2017 at 14:46
  • The core of my disagreement lies in the idea of a "core group" or of designated "moderators", not in the fact that moderation is needed. Why do Y and Z approve a bad edit? They suffer from the same lack of guidelines than X. On Q&A, community moderation seems to work pretty well. It's not perfect, but we all participate because we can identify spam, link-only answers, typos, edits that seem to modify the intent of the author, etc. Every now and then people come to meta for some clarifications but all in all the roles (of users, reviewers, ...) and the goals of Q&A are pretty clear.
    – Cimbali
    Commented Feb 14, 2017 at 15:14
  • 3
    Unlike Cimbali, I strongly agree with your view. However, I think "tag moderators" would have too much overhead (in terms of developer, moderator and community team time). Better to start by making the review queue less broad -- like don't show random folks my r edits; only show it to those with that queue filter active.
    – Frank
    Commented Feb 14, 2017 at 19:21
  • 8
    @Cimbali in Q&A, edits are relatively restricted and heavily moderated, and the posts belong to someone. If someone repeatedly posts bad content, they get banned. This isn't happening in documentation. We can't rate the quality of an individual user's contributions as effectively as we can in Q&A. There's little to no accountability or penalties to suggesting edits.
    – Kevin B
    Commented Feb 14, 2017 at 20:06

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