230

The current system rewards writing documentation that is already covered by the official docs. Meanwhile, popular libraries without good official docs are undercontributed. The system is broken, and it needs fixing. This result runs counter to how Docs was pitched:

Q: What should be documented?
A: Anything where we can actually make it better. If a project already has awesome documentation that's easy to search and cite, then there's no need to duplicate it on Stack Overflow. We're interested in fixing what's broken with documentation, not just moving them onto Stack Overflow. --announcement in Aug 2015

Let's take as an example the Boost library. The official documentation is pretty lackluster, consisting of 404'd links and unclear explanations. This is when Stack Overflow documentation would be most useful. Right now, the Boost documentation has one example with one topic.

The current reputation system encourages people to write documentation that don't need to be rewritten. The front page shouldn't be filled with C#, Android, and Python - they should be filled with the topics without good official documentation, like Boost or LEMON. The popular topics are popular because they are easy to write, not because there is an actual need for the documentation.

The Boost Python documentation (and the Boost documentation in general) are very short and don't have many examples. It would take several hours digging through the reference guide and source code to do anything beyond what is described in the tutorial. We need to pool our knowledge to save people from those hours of digging.

We need to have a way to draw attention to a topic. Otherwise, topics like the Boost documentation would never grow, and developers would continue to get frustrated.

How else should we encourage users to contribute to undercontributed (for lack of better word) topics?

If you think that there aren't documentation topics that aren't fully covered by the official documentation, just look at the LEMON graph library or my aforementioned Boost documentation. The documentation for one of the core features (Map data types) is still under construction and the current examples won't compile. They've been in such a state for years.

Right now, the topics people contribute to most are already covered by the official documentation, while the topics people contribute to the least are the ones that aren't covered by the official documentation. This is because it is easy to write documentation when there is a clear official documentation, and it is hard to do so when there isn't - you'll have to spend several hours navigating the source code for clues. The popular documentation is popular because it is easy to write.

Summary

Whatever the solution, I believe that the current system is broken. It encourages making documentation that are covered by the official documentation. It puts topics in the spotlight simply because they're popular, not because they need contributors. It rewards those who contribute to popular documentation, not the documentation that need contribution. It should reward those that contribute to the documentation that needs it the most, not the most popular ones. Which, by definition of "popularity" already have plenty of contribution.

One prime example is Boost, likely the #1 used C++ library, with bad official documentation and only one example in Stack Overflow Documentation.

The system rewards contributing to documentation that don't need contribution, and buries documentation that needs it very deeply.

It does the opposite of what it should be doing.

The current system is broken. It needs fixing. How?

Stack Overflow docs should be replacing bad docs, not rewriting already good docs.


The documentation you see are the documentation that are easy to write. The documentation that are hard to write are hidden. This is why (quoting Louis) someone can say "I've not seen one bit of Docs that was not already covered perfectly in official or as-official-as-it-gets community-maintained documentation".

I encourage you to post an answer - it'll take more than implementing a single answer to fix this problem.

I apologize for the repetition - it is needed to avoid misunderstanding unfortunately.

If you want more examples, see CMake. Widely used, with lackluster documentation. (not a single example given for something as important as include directories!). And the Stack Overflow Docs are currently minimal at best.


Clarification: The things I said about Boost.python apply to Boost in general, not just for the Python submodule.

Wow! 47 votes! Most of my meta posts have negative votes. I never expected this many votes. Funny this was -6 votes for a while before...

57
  • 108
    There's plenty of evidence that people are participating in Documentation for the wrong reason (i.e. reputation rather than making a relevant difference). I've not seen one bit of Docs that was not already covered perfectly in official or as-official-as-it-gets community-maintained documentation, or that was no flat out plagiarism, or that was not an attempt at exacting rent (submit a code dump that others will explain, and reap the rewards forever and ever). Why oh why should we put into a place a system that will give people more incentive to participate for the wrong reasons??
    – Louis
    Commented Aug 8, 2016 at 17:02
  • 10
    @uoɥʇʎPʎzɐɹC I can't get into an extended discussion now. I'm not a fan of bounties even on the Q&A side. As much as I like to get the bounty once in a while, I find that most bounties (not all, but most) are put on question that are mediocre if not downright off-topic. I see a lot of answers on them that are slapdash attempts at getting in on the action. It may be surprising but a lot of people are motivated to do things just for the common good. Wikipedia, for instance, gives no rep points. I'm not saying "ditch the points" but I'd rather not put more emphasis on them.
    – Louis
    Commented Aug 8, 2016 at 17:25
  • 37
    The purpose of docs is not to document undocumented things. The purpose of docs is to make money for SO by putting job ads beside the docs. As such it's totally in SO's interests that ALL docs appear on SO Docs.
    – user128511
    Commented Aug 8, 2016 at 18:02
  • 6
    @gman more people will visit if the site contains documentation which is not covered by official docs. Commented Aug 8, 2016 at 18:07
  • 4
    I disagree with so docs being fundamentally broken. Popular tags are being contributed to, less than popular tags aren't. What exactly is wrong with that? The lemon graph library tag only has 34 questions! Boost has 18k, so i could see some use in it being documented here if the official docs aren't good enough, but if noone wants to do it... what do you suppose we do about that? I doubt moving it to the front of the list will help with that. Increasing rewards will just cause the more popular ones to be contributed to more because they're the ones receiving upvotes.
    – Kevin B
    Commented Aug 8, 2016 at 18:33
  • 2
    @KevinB yeah, and the Boost SO docs have one example and one tag. That's why it's fundamentally broken. Commented Aug 8, 2016 at 18:34
  • 6
    @Louis "I've not seen one bit of Docs that was not already covered perfectly in official or as-official-as-it-gets community-maintained documentation," While I don't disagree with your main point, I am seeing some things that are a bit better than this. Sometimes official documentation isn't organized wonderfully. An experienced user familiar with the documentation knows where to find the relevant bits, but they're not all together. Some areas of documentation are helping to get some of these kinds of cross-references together. Commented Aug 8, 2016 at 18:35
  • 5
    For example, SO Docs for jQuery is damn near useless, since jQuery is so well documented. Javascript's documentation on the other hand is very fragmented and often lacks real-world examples.
    – Kevin B
    Commented Aug 8, 2016 at 18:41
  • 4
    @uoɥʇʎPʎzɐɹC: I think Boost's documentation is very good, as far as normal documentation is concerned. For most Boost libraries, the behavior of functions and classes is explained and so forth. It may not have examples for every function/class, but if you're able to process C++ standardese, you should be able to understand Boost's documentation reasonably well. Commented Aug 8, 2016 at 20:31
  • 6
    The number of times you’re using the word “Boost” in your question and elsewhere in this discussion leads me to suspect that you have an axe to grind. Which is bizarre, but whatever. I agree with @NicolBolas that Boost actually has one of the best, most complete official documentations around. It could be even better, and some libraries are lacking examples, but in general it’s complete — as in, every aspect of the API in question is covered. Single faulty links (though I can’t find any) notwithstanding. Commented Aug 8, 2016 at 23:11
  • 17
    I'm still confused (not by you) as to whether Documentation is trying to be "official-ish documentation" that's simply hosted on Stack Overflow, or if it's trying to be something quite different from what comes to mind when we think of the word "documentation".
    – BoltClock Mod
    Commented Aug 9, 2016 at 4:10
  • 12
    Documentation is so broke, and mixing it with SO reputation was so wrong that I stopped contributing to Q&A as well. Documentation should be something like Tag wiki's or community wiki posts that people creates voluntarily.
    – T J
    Commented Aug 9, 2016 at 5:46
  • 6
    @JoshuaTaylor "Sometimes official documentation isn't organized wonderfully. " and uoɥʇʎPʎzɐɹC " If something takes thirty minutes to locate, it's worth rewriting in SO docs." Can you enlighten me as to how hodge-podge of random and everchanging examples that are SO.Docs is better organization and will help with finding something in less than 30 minutes?
    – Mamut
    Commented Aug 9, 2016 at 12:05
  • 3
    "SO Docs was designed to replace bad docs": how are SO.Docs going to do that, exactly? That's exactly what I asked above: meta.stackoverflow.com/questions/331946/…
    – Mamut
    Commented Aug 11, 2016 at 14:29
  • 5
    This is exactly the reason why I haven't even opened SO Docs, let alone contributed to them, despite being a rather active user on the main site. I saw this would happen from the very beginning - all the "popular" languages and tags with good to great docs would get repeated, and lesser-used languages or libraries (like your LEMON example) would be ignored. People come to SO to find answers to questions they can't find elsewhere. The same should be true of docs. Documentation by popularity contest (and rep) is just a bad idea.
    – MattDMo
    Commented Aug 11, 2016 at 16:59

13 Answers 13

47

Nothing can magically fix it right now

Popularity

You're saying, "The popular documentation is popular because it is easy to write." Wrong. Popular documentation is popular because it is popular. If I program in C#, Java, Python etc., nothing can get me interested in digging through sources of obscure Boost libraries to write explanations of stuff I'll never use. LEMON graph library you say? The thing which has 34 questions (10 unanswered)? In terms of Stack Overflow, nobody is using it. And among those nobodies you need to find several experts who will spend their precious time on writing documentation.

Look at the Q&A part of Stack Overflow. Is it any different? Answers on popular and trendy topics receive most upvotes. Answer a trivial question on JavaScript within the first 30 seconds after the question was asked — 10 upvotes, spend an hour on a well-thought answer on LEMON or whatever — you're lucky if you get a single upvote.

It's already broken. Literally nothing was done to fix it on Q&A. It's been in this state for years. Why do you think that a miracle will happen and Docs will be any different? It's broken in all the same ways, just with bonus multiplying of reputation.

Priority

Let's suppose I'm an expert on the LEMON graph library and want to share my knowledge with others. Why on Earth would I write documentation on Stack Overflow's Documentation, which is

  1. in Beta stage, so it's full of bugs and nobody can guarantee it'll still exist in a month;

  2. full of rep farmers, robo-reviewers and all glorious things we love Stack Overflow for;

  3. limited to a flat list of "topics" and "examples", discouraging writing sensible documentation, like deep explanations, tutorials, etc.;

  4. not part of the official or semi-official documentation, so nobody will ever find it?

If I decide to write documentation, I'll find the maintainer of the website and discuss improving official documentation. A lot of projects have wikis, documentation in source code repositories, etc., so it's even easier — just make a pull request. Heck, I may even prefer good old blog posts, because they're much more flexible.

Solutions?

Let's play around with what we have. Let's make Documentation a good place. Let's make it look like something useful. Let's fix numerous bugs. Let's make Documentation more flexible. Only then we can expect people to spend their time to write good documentation.

  1. If you want a quick and dirty solution, bounties, suggested by others, sound like a good idea.

  2. Fixing sorting can help to distribute upvotes more fairly.

  3. Lowering bars for creating tags won't help — even with the current limits, most tags a already dead.

6
  • 15
    I agree. Generally, I find it tedious enough to document my own code. If I enjoyed writing documentation, I would contribute to the official documentation (which for my language of choice offers also the advantage of being available offline) and not to an unstructured mess without a clear vision. SO Q&A works for me because I have direct interaction with at least one person I'm helping and because I get to solve "puzzles". Both incentives are missing in SO Docs.
    – Roland
    Commented Aug 9, 2016 at 7:22
  • I agree with the solutions part (except for no. 3), but what about Boost? It's the #1 C++ library and it has one example. Commented Aug 9, 2016 at 14:18
  • @uoɥʇʎPʎzɐɹC To put it bluntly, I think C++ developers with good enough experience in boost to write documentation have enough brains to put their knowledge to use where it'll actually be useful (see "Priority" section). :)
    – Athari
    Commented Aug 9, 2016 at 14:56
  • @Squidward then why are Python and Java on top but not Boost? Commented Aug 9, 2016 at 15:00
  • 2
    @uoɥʇʎPʎzɐɹC Because they're more popular, so proportionally more inexperienced devs to write docs of questionable quality? :) python = 613K, java = 1116K, boost = 18K.
    – Athari
    Commented Aug 9, 2016 at 15:17
  • 2
    I don't agree with this. I honestly don't believe that "Creating a new console application in C#" is that popular/useful to people. Yeah it's good and detailed, but I think it is easy to write, and that there are a million examples of how to do this already on the Internet.
    – Ian
    Commented Sep 15, 2016 at 8:57
33

Lower the bar for instant edits and reviews based on tag size

Since the last update (Aug 4), those with silver and gold badges can skip reviews for their edits. However, small tags like have no such users. As David Postill explained in an answer to the last update, this is a real obstacle to editing docs for small tags.

The bar for these powers could be lowered based on the total tag score (added up over all answers in a tag). For example:

  • Up to 1k total tag score, edits and reviews are free for those with 25+ tag score.
  • Up to 2k, the bar is 50.
  • Up to 3k, the bar is 150.
  • Up to 4k, the bar is 250.
  • Up to 5k, the bar is 350.
  • For 5001+, the bar is 400 (silver badge).
5
  • 1
    @uoɥʇʎPʎzɐɹC I'm not talking about creating tags, just editing within the tag (assuming it has been created). I think you need a score of 1 to vote to create a tag's docs (?).
    – Frank
    Commented Aug 8, 2016 at 18:10
  • 2
    In the case of batch-files there are users with enough rep to approve changes, but they don't seem to be (interested in) visiting stackoverflow.com/documentation/batch-file to review and hopefully approve the changes :/ Commented Aug 8, 2016 at 19:52
  • 1
    @DavidPostill Yeah, I've found that's a common problem with wikis -- a dearth of willing editors who also have the skill and knowledge to make good edits. And in the long run, there's usually a problem keeping such people around so the wiki doesn't fall out-of-date or get edited with wrong info. Anyway, yeah, I guess this recommendation doesn't help you much there.
    – Frank
    Commented Aug 8, 2016 at 19:59
  • 3
    I'm not sure this will make people to participate more... I frankly don't participate because the only tech I use have extensive and complete documentations.
    – Braiam
    Commented Aug 8, 2016 at 20:12
  • 1
    This should also be lowered the more reputation the user has Commented Aug 8, 2016 at 22:17
18

Have Bounties

It works for Q&A, so why not for Documentation too.

I suggest that people can put a bounty on creating/improving a certain topic of a certain tag, which then runs for a certain time and the bounty reputation (that could also come from the Q&A part of the bounty offerer) is then spread evenly/non-evenly among all who contributed towards this topics during the runtime of the bounty and maybe the bounty giver should have a say too (like 50% of the bounty is assigned in any case, the other 50% only if the bounty giver is satisfied with the result).

Let's use bounties as one way to get docs we really need.

14
  • 4
    What if someone needs documentation, but they're a beginner and so don't have much rep to spare?
    – nafg
    Commented Aug 8, 2016 at 20:05
  • 4
    I think bounties might be an idea for later but at the current systems I think this would just created a rush to copy and paste or make small edits in an attempt to get bounty or part of the upvote rep from an example that adding a bounty would probably cause. Commented Aug 8, 2016 at 20:06
  • 1
    @nafg They can still propose topics and request improvements (or ask their questions on the Q&A part) or do some other activities to get more rep. Commented Aug 8, 2016 at 20:08
  • 3
    @JGreenwell I feel like Bounties alone will not solve that problem but it will help going towards the right direction. The goal is to creative incentives to make Documentation that you need to read (not to write). Bounties is one way and if the bounty giver has a say too I guess that they would do some good there. Commented Aug 8, 2016 at 20:10
  • It suprises me that my question initially suggested a bounty system and I had to remove to receive upvotes. Commented Aug 8, 2016 at 20:17
  • 3
    I'm not disagreeing with the idea of bounties - just that there would also need to be a way to pick contributor (rather then most edited or created) much like accepting in Q&A and a lot of work determining how bounty could be split among editors (and still have problem of +5 per upvote which bounties attract) - i.e. not a bad idea just a caution on it possible back-firing if not really planned out. Commented Aug 8, 2016 at 20:22
  • Maybe bounties and upvotes on topic/improvement requests could be tied together, e.g. an upvote equals a 10 point bounty, and the total bounty is awarded to the person who fulfills the request.
    – siffiejoe
    Commented Aug 8, 2016 at 20:29
  • 1
    "Bounties" are the default answer for rewarding quality answers on the main site, yet we receive daily complaints about crap posts. So how are bounties going to be different here? Commented Aug 8, 2016 at 20:49
  • @uhohsomebodyneedsapupper That's why I said they they definitely won't solve the problem alone. The idea of bounties in Documentation is that you can reward docs that you want to read, not only docs that is already written but not interesting because it exists better elsewhere. It's an option on future content. Commented Aug 8, 2016 at 20:53
  • @nafg: By copying already published documentation for some unrelated and well-covered topic just to farm rep, obviously. Commented Aug 8, 2016 at 20:55
  • 1
    @uhoh Tbh, I've yet to find something I want to bounty on Q&A, but can imagine plenty of things to bounty in Docs, in the spirit of meta.stackoverflow.com/q/254137
    – Frank
    Commented Aug 8, 2016 at 20:58
  • original question that was downvoted to -6: meta.stackoverflow.com/revisions/331946/1 Commented Aug 8, 2016 at 22:11
  • @uoɥʇʎPʎzɐɹC Now it's at +84. Probably means that voting is correlated, i.e. votes strongly depend on what the current score is, amplifying small trends or fluctuations and leading to inconsistent output. Commented Aug 9, 2016 at 6:38
  • @Trilarion I predicted that it would skyrocket after reaching +4 Commented Aug 9, 2016 at 14:16
9

I think most of the popular languages/technologies have decent documentation. Are they popular because of the great documentation? Maybe. Does great documentation get created already (outside Documentation) when a language/technology is popular? Probably.

The relevance this has to Documentation is the fact that only "popular" tags are eligible for Documentation, because it's only in beta.

(In my opinion, the Documentation for third party libraries should be separate from the language Documentation. In its own tag.)

Even under the current system, it's not working too well for small (but eligible) tags. Pending improvements have to wait forever for approval. If people are unfamiliar with the content in an edit, they are unlikely to review it.

Other changes to the system are necessary, especially for the review queues, before it makes sense to address smaller tags and niche technologies.

14
  • 1
    Did you look at the Boost.python documentation or LEMON? Commented Aug 8, 2016 at 18:05
  • LEMON isn't for python Commented Aug 8, 2016 at 18:17
  • 2
    Boost is popular but has very little official docs or SO docs. Commented Aug 8, 2016 at 18:17
  • Isn't this LEMON? And while Boost is popular enough, I haven't heard of anyone using it in Python. (You said yourself that it's low activity...)
    – Laurel
    Commented Aug 8, 2016 at 18:19
  • Boost.python is a C++ API that simplifies Python's framework for writing extensions. It makes it much easier to interact with python. Commented Aug 8, 2016 at 18:20
  • It's LEMON: lemon.cs.elte.hu Commented Aug 8, 2016 at 18:20
  • 1
    Boost in general has little docs on SO. Commented Aug 8, 2016 at 18:21
  • 1
    Counterexample: Boost is very popular and has bad documentation. Commented Aug 8, 2016 at 18:26
  • 1
    "Popular" is subjective. It wasn't popular enough to have existed during the private beta (compared with C++ for example). Good content takes time, especially when it is not attracting the people who are attracted to the popular topics. Did you really expect to see great content immediately, especially if the official docs are as bad as you say?
    – Laurel
    Commented Aug 8, 2016 at 18:46
  • Boost is probably the #1 used library. It has one example. It takes time, so it should be in the spotlight. Commented Aug 8, 2016 at 18:49
  • 1
    That's not how tag sorting works currently; it's sorted by how many topics exist already.
    – Laurel
    Commented Aug 8, 2016 at 18:51
  • more topics = more contribution = more popular Commented Aug 8, 2016 at 18:52
  • 1
    LEMON is another odd example: It seems to have an amazingly exhaustive documentation and introductory tutorial, stuffed with examples. I’m honestly puzzled about what you might be missing from it. Commented Aug 8, 2016 at 23:16
  • 2
    So much this. I've complained in half a dozen places on meta that we don't need C# docs that already exist on MSDN. What we need are docs for libraries that don't have good documentation like ANTLR, Moq, LibGit2Sharp, Ninject (ok, Ninject is best of the bunch, but still). Yet we've not been able to create many of these because... Why? Reasons? Idk.
    – RubberDuck
    Commented Aug 21, 2016 at 11:19
7

A system to vote for documentation that needs contribution, and filling the front page with these topics.

Like Steam greenlight for documentation.

Voting should be on a scale "highly desire" to "mildly desire" so that smaller tags with less participation can benefit too.

A queue/page showing only topics with these votes

This is so that these pages can accumulate these votes. This must be semi-random to give a chance for unpopular topics to be in the spotlight.

Increasing reputation rewards for significant contributions to a topic with many of these votes

  • Direct extra reputation upon significant edits (+10 or +20)
    • More reputation for topics with little official documentation
  • 5 "highly desire" votes should qualify a tag for this but not, say, 10 "mildly desire" votes.
    • Small tags need documentation, too.
  • A vetting system would be required to remove a topic from this status, too.
  • Putting such topics on the main page with a "Featured" label and a manilla color. (just an example)
  • Unpopular tags would be able to get in through many "highly desire" votes.
  • The bar should be set low to allow unpopular tags to get through.
  • Downvotes should exist too to prevent popular tags from being greenlighted
  • It should be made clear to the user that greenlighting is only for tags that have bad official docs or would other wise need it.

Ideas to throw around

  • A system to determine how much effort (browsing through source) was put in, and rewarding extra reputation this way.
4
  • 2
    "popular" tags will always receive more of them.
    – Kevin B
    Commented Aug 8, 2016 at 21:51
  • @KevinB I intentionally put the bar low for this, and unpopular tags would be able to get in through "highly desire" votes. Commented Aug 8, 2016 at 22:01
  • This is a bit unclear as to whether you're talking about tags or topics (or both); these are two different things in Docs. Commented Aug 8, 2016 at 22:57
  • @MikeMcCaughan tags, sorry Commented Aug 8, 2016 at 22:58
7

Quoting the original post:

Q: What should be documented? A: Anything where we can actually make it better. If a project already has awesome documentation that's easy to search and cite, then there's no need to duplicate it on Stack Overflow. We're interested in fixing what's broken with documentation, not just moving them onto Stack Overflow. --announcement in Aug 2015

This is the problem with Documentation in general. If there's something lacking in the original Documentation, why don't we just edit it? This will surely be beneficial to more demographics in the long run as even if SO improves the UI and gains good search results like it does for Q&A, many users may prefer to stick to the official documentation. Documentation works where editing the original source is simply infeasible. For example, the Python documentation is spaghetti.

My suggestion is to attach each topic to a canonical (authoritative) reference link

The benefits of this:

  • Deters plagiarism. It becomes trivial to compare the post to the original and it deters people from simply copy/pasting.

  • Keeps the topic "on-topic". Some of us don't like the narrative/tutorial nature. Neither do I. Why do we need yet another "Hello World" tutorial? There are hundreds of books written on the subject. If we pick a discrete source to expand off of, we don't go off into tangents that belong in books.

  • Helps people figure out what is wrong in the original source. Writing is a process. You get better at it by constantly revising, and so does the material. Sometimes things don't really come to you until you actually put your thoughts on paper. If we have no point of origin, people will ramble and duplicate information.

In the end, they might even realize that writing the Documentation topic is a waste of time and they'll go and edit the original source. This is a good thing. Then whatever's left over hopefully is a polished gem that makes a good article for Documentation. We actually already see this format in the Q&A (main site) when people provide longer explanations for tufts of text.

A rather ambitious idea, but one worthy of contemplation I think.

Prime example of a great addition to the Python documentation on the Q&A section

7
  • we can't edit the original documentation isn't possible Commented Aug 8, 2016 at 22:08
  • uhm. yes it is, in some cases.
    – Kevin B
    Commented Aug 8, 2016 at 22:08
  • 1
    MDN, cppreference are two examples that immediately come to mind as they're wikis. Other examples are "open source" (you can raise issues on GitHub, even the ISO C++ specification is open to the public.) Barring that, there's mailing lists, bug trackers, etc. Point is, for the majority of cases that I've seen it's not impossible. But what I meant was the Python documentation is so dense and loosely organized that it's probably better just to expand on it than editing it. Commented Aug 8, 2016 at 22:12
  • 1
    I guess you are not a fan of having topics be tasks, then? meta.stackoverflow.com/q/329183 Tasks often use multiple tools with disparate doc pages. Besides, links die and the authoritative docs in R and Stata are those bundled with the software (and referred to like help stata_thing or help("r_thing") on SO), not links.
    – Frank
    Commented Aug 8, 2016 at 23:00
  • @Frank Links die, but information also rots. Unless you're claiming that Documentation can be version-agnostic/future proof. It's possible to incorporate an authoritative reference with a citation just as easy as it is to make a link and there's mirrors available most of the time. Commented Aug 8, 2016 at 23:17
  • 2
    @Frank RE the proposal: it sounds like a glorified rosettacode. The problem with it is that the examples are way too localized as they're complete programs and not examples for reference. Commented Aug 8, 2016 at 23:20
  • 1
    I think your understanding of what can be done with Docs is too limited. There are common problems R users face, for example, that do not center around a single function with a single doc one can point at (with a link or anything else). Even such a simple and central concept as missing data involves several functions: stackoverflow.com/documentation/r/3388/…
    – Frank
    Commented Aug 9, 2016 at 0:46
7

Lowering the bar for topic creation for low-activity tags

  • tags such as are low activity, yet the framework behind them is widely used.
  • 500 questions is too much. The better the documentation, the faster people ask questions.

A framework has momentum. Friction reduces new acceleration. Guides like Documentation reduce friction. But the 500 question limit is asking for a large momentum.

7
  • 1
    What do you have in mind? Might want to refer to whatever the current requirements are. (I'm not sure, but here's what the help center claims: stackoverflow.com/help/documentation-add-tags )
    – Frank
    Commented Aug 8, 2016 at 18:20
  • 1
    Why would this help? All it would do is encourage people to throw whatever examples they want onto the site. A tag without supervision or some form of cohesion will become a random grab-bag of factoids. Or worse, nothing at all. Commented Aug 8, 2016 at 20:29
  • 1
    @NicolBolas this is a real obstacle for many smaller tags Commented Aug 9, 2016 at 14:16
  • @uoɥʇʎPʎzɐɹC: ... so what? Smaller tags are smaller because they don't have many people who are experts that participate on the site. Therefore, they won't have many people who will edit their documentation. Thus, it will turn into garbage. Witness the OpenGL Docs.SO tag. Commented Aug 9, 2016 at 14:42
  • @NicolBolas see edit Commented Aug 9, 2016 at 14:44
  • So much this. I've complained in half a dozen places on meta that we don't need C# docs that already exist on MSDN. What we need are docs for libraries that don't have good documentation like ANTLR, Moq, LibGit2Sharp, Ninject (ok, Ninject is best of the bunch, but still). Yet we've not been able to create many of these because... Why? Reasons? Idk.
    – RubberDuck
    Commented Aug 21, 2016 at 11:20
  • @RubberDuck you totally agree with me. I like that. :P Commented Aug 21, 2016 at 15:38
-1

This problem comes from Q&A. If you have a common known question in a popular tag, you get a lot of action.

But if you have a tricky question in a tag with not so many active members, or on the interaction between several tags or on a site of the network that's very small prepare for the tumbleweed avalanche.

The voting system scales with activity.

To fix this, make rewards scale with unavailability, not activity.

Imagine you are stuck with the regular documentation. You post a request here to get an example. Now you earn rep for every day (or hour or week or whatever) that there is no example.

People are gaming the system. It's time that the system games the people.

This is a very rough idea1 and I don't know how reputation would work exactly for all participants. But as you say, the core philosophy of docs is to make somebody care to write documentation that previously nobody cared to write. The first step is to reward people for pointing out missing documentation.

Of course this assumes a separate rep count on docs (from Q&A) and reasonable moderation tools.

1 I assume this is rather controversial and haven't thought this through in all details. If this doesn't get super low score I'd like to develop the idea further.

5
  • 1
    Woudl of course have to have a way to prevent people from earn rep waiting for someone to write documentation for array. Oh, wow, that actually happened...
    – Kevin B
    Commented Aug 8, 2016 at 20:50
  • 2
    @Kevin B given the most common thing people complain about on meta, there's an army of members that want to stop constant reputation gain. This merely declares "writing missing documentation" the only useable weapon in this war.
    – null
    Commented Aug 8, 2016 at 21:03
  • 5
    I agree with the reasoning in this post, but I'm not sure about the proposal. Commented Aug 8, 2016 at 21:48
  • @uoɥʇʎPʎzɐɹC it's similar to your suggestion, except that the measure of what should be documented next is not based on votes that can be biased by popularity.
    – null
    Commented Aug 8, 2016 at 22:34
  • 1
    I can't agree with this proposal when stupid proposals exist without any way to prevent it (except waiting for it to die). If Q&A is anything to tell (some of the worst things I have seen were tumbleweeds), this will not scale.
    – Laurel
    Commented Aug 9, 2016 at 1:43
-2

Decreasing reputation rewards for topics with good official docs

This could be implemented through a voting system.

Clearly, the reputation system shouldn't reward contributing to "Python" when the official docs are already pretty good. Again, this runs counter to the design philosophy of Documentation.

4
  • why the downvotes? Commented Aug 9, 2016 at 1:28
  • How do you tell which ones have good official docs?
    – Kevin B
    Commented Aug 9, 2016 at 14:55
  • @KevinB voting system? Commented Aug 9, 2016 at 15:01
  • 4
    which... will still just be a popularity contest.
    – Kevin B
    Commented Aug 9, 2016 at 18:03
-6

The ability to place a bounty on a topic request.

This is a manifestation of the somewhat vague proposal to add bounties.

Creating the topic doesn't result in the bounty being awarded. Instead, (hypothetically) people would contribute to the example and the bounty would be awarded to the user (judged by the bounty-maker) who contributed the most. Usually, that user will have singlehandedly created the topic.

This is so that vampires can't just create a small (but on-topic) response to a request and win the bounty.

(Optionally) During the bounty period, multiple competing versions of documentation could be created to let different people express ideas in wildly different formats without conflicting. All versions will be editable by anyone. The ideas from alternate versions could be incorporated into the one that is chosen to become the documentation when the bounty period is over.

Some ideas for how that would be chosen:

  • By the bounty giver (seems a bit unfair)
  • By the community in the forms of votes. Ties could be broken through:
    • The community
    • By the bounty giver
1
-6

Stack Overflow is notoriously used for questions that are explained much better by documentation, mostly for two reasons I believe:

  1. A separate page on each topic manages to get referenced really well
  2. Often the reader doesn't want the details, just the self-explanatory code snippet.

Let's take a very simple example, since you like Python. Say I want to copy a list, and I google "python copy list".

My two main results are

  1. How to clone or copy a list?
  2. https://docs.python.org/3/library/copy.html

The second link has all that you want, with proper well-organized explanation and an (inline) code snippet for the slice notation (and is event a link to the Python 3 documentation, for once). However, the first one is much more straight to the point. And that's the idea behind organizing Documentation in examples: KISS.

The most popular tags will get the most questions, answers, documentation, and all of it. Be it by noobs, by experienced users experienced on different tags who don't want too sift through lengthy explanations, or by intermediate users who want to contribute their knowledge on what they know.

Just go through questions that are upvoted the most, or better yet that are protected against low-rep "+1" spam. You'll just see how many of those are mind-bogglingly trivial.

That non-popular things get less attention is not Documentation being "broken", it's inherent - if not by design. Removing barriers and adding incentives to contributing in less popular tags is a good thing, but I don't think there's fundamental any way around the fact that Documentation will inexorably end up repeating all the pre-existing useful documentation. And readily useful documentation doesn't mean it can't be made better, either.

6
  • Did you read the question? My question's main point is drawing more attention to tags whose official documentation is extremely lackluster. Commented Aug 9, 2016 at 1:28
  • Yeah, and you're also saying that those tags missing content means "documentation is broken". It is, in fact, unavoidable.
    – Cimbali
    Commented Aug 9, 2016 at 1:39
  • Documentation puts the tags with good official documentation in the spotlight; just take a look at the front page Commented Aug 9, 2016 at 1:43
  • @uoɥʇʎPʎzɐɹC no, it puts tags that are popular in the spotlight. If the tag is popular, you are more likely to gain rep on substantial edits, making editing there more productive. Then there's also the fact that more people are familiar with the tag.
    – Kevin B
    Commented Aug 9, 2016 at 17:24
  • @KevinB only popular because it's easy to write, easy to write because there are good official docs Commented Aug 9, 2016 at 19:49
  • 1
    or... because far more people use it. By your argument the jQuery tag would be going crazy right now.
    – Kevin B
    Commented Aug 9, 2016 at 19:50
-10

Rewarding those who contribute to undercontributed docs with reputation

Because when there's no good official docs, you have to dive into the source. We should reward people who take the effort to dive into the source.

We can reward people proportionally to how many "greenlight" votes they have.

9
  • 4
    Reward them in what way? more per upvote? an amount just for getting something approved? at what point does it go from being undercontributed to not undercontributed? I think that's going to depend heavily on the tag being documented, not just it's question/answer stats.
    – Kevin B
    Commented Aug 8, 2016 at 19:23
  • 2
    How would you determine which Documentation topics qualify for this?
    – TylerH
    Commented Aug 8, 2016 at 20:53
  • @TylerH see the greenlight idea Commented Aug 8, 2016 at 21:30
  • @KevinB similar to the bounty idea. Commented Aug 8, 2016 at 21:30
  • @uoɥʇʎPʎzɐɹC Except only people who use those languages will care about them. Why should users with bigger communities get a bigger reward just because more users are available from the pool to vote for them? This seems to go against the issue mentioned in the question which is that smaller tags are in more dire need and therefore need some incentives.
    – TylerH
    Commented Aug 8, 2016 at 21:31
  • Look at it this way. I agree, we need to somehow get users to want to contribute to things that need to be contributed to. but... i'm not seeing any solutions. None of the suggested solutions actually go into detail of how to implement it. First we have to be able to identify what exactly needs to be contributed to! you can't just say "Oh, tag X has 20k questions, so until it has Y topics/examples we'll give them more rep!" because there's A LOT of tags with 20k+ questions that need absolutely no documentation added to SO docs under that specific tag.
    – Kevin B
    Commented Aug 8, 2016 at 21:40
  • @KevinB see the updated greenlight answer Commented Aug 8, 2016 at 21:46
  • I don't see how that gets around the whole "noone's contributing" problem. If noone's contributing, what makes you think they'll "greenling vote" it?
    – Kevin B
    Commented Aug 8, 2016 at 21:49
  • @KevinB If a single vote is reached, then it will be featured on a page in a random fashion. Commented Aug 8, 2016 at 22:02
-19

Reputation rewards

I remain neutral on this topic. Please vote on this answer. This is gauging the community's response to reputation rewards.

Note that just because the current reputation system doesn't work doesn't mean this won't work in the future.

2
  • 2
    I'm confused. Does downvoting this mean you think there should be no reputation associated with Docs? Commented Aug 8, 2016 at 21:50
  • 3
    @ThisSuitIsBlackNot Downvote = No, we should not give extra rep to people who contribute to topics that need contribution Commented Aug 8, 2016 at 21:51

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