283

Are there any stats for Documentation about the activity in a specific tag? I have observed that a niche tag like MATLAB is pretty much dead (last action on Dec 2nd). I personally lost interest in contributing to that niche a while back.

Is this a common trend for the whole docs?

UPDATE

Stats that would be interesting to look at (as suggested in the comments):

  • Number of links to Documentation in SO Q&A
  • Number of links within Documentation (proxy for repetition)
  • Contributions, i.e., edits, size of edits, new topics, ...
  • Who is contributing
  • Views per topic

It would be nice to have them over time.

Thanks to Shog9 we have some stats under his answer.

UPDATE 2

I particularly liked JonH's comment about removing reputation points gain from Docs, and I will repeat it here, as it's buried down under:

Get rid of rep on documentation immediately. I mentioned this in the initial beta. The people who want to write good docs don't need any rep. The people who don't know how to write docs want all the rep they can get so they will do anything to get it.

I think this issue, already raised here, is central to the future of Documentation.

While it is harder to control for quality without a strict set of rules, taking the reputation points incentive away might retain only the really motivated contributors, while eliminating the noise.

UPDATE 3

It's been a week, and I wonder if the Stack Overflow team has a couple of words to spare about their expectations and the general vision for Docs, given that the stats, although not conclusive, are slowing confirming the main question raised by this thread.

Adam Lear has promptly replied:

Re: update #3, yes, we have a few thoughts. We have followed this entire post and had a number of discussions internally as a result, in addition to our usual planning/status meetings and whatnot. We'll post something up in the next couple days.

And a full meta answer is now here. It basically reads as, the team is listening to our feedback and willing to correct the direction, but resources are not infinite, so it will take time. Time is also needed to see a response from the community, which is not necessarily expected to be a community of experts.

56
  • 174
    Docs were a failed attempt from the beginning IMO. Commented Dec 11, 2016 at 23:40
  • 15
    What kind of stats would you like? The stats I have handy show a huge uptick lately, but may not reflect your area of interest; I can probably dig something up if you let me know what sort of metrics you're interested in though.
    – Shog9
    Commented Dec 12, 2016 at 0:07
  • 53
    The official MATLAB documentation is awesome. So, in my opinion, there is really no need for an SO documentation on MATLAB. And that is probably why it is more or less dead now. Still, there are lots of badly (if at all) documented languages, frameworks, and tools - so don't judge based on one tag.
    – hbaderts
    Commented Dec 12, 2016 at 2:29
  • 26
    So far SO Documentation doesn't come up in Google search results. I think if it did it would be used a lot more.
    – Suragch
    Commented Dec 12, 2016 at 6:09
  • 19
    I think it could be really great to be able to close SO questions as duplicates of Docs entries. Commented Dec 12, 2016 at 6:22
  • 41
    Throwing away free reputation, people copy pasting from random websites, robo reviewers are ready to accept minor, unhelpful, incorrect changes, what else can go wrong?
    – Mr. Alien
    Commented Dec 12, 2016 at 6:57
  • 38
    Well, I don't know if its dying or not, but the fact that garbage like this got approved by a C++ silver badge holder does not in any way make me confident that Docs.SO is producing quality work. Commented Dec 12, 2016 at 6:57
  • 66
    @Shog9: One of the prime motivators for Docs.SO when it was first suggested was to "mitigate a source of repetitious (often exact duplicate) Questions". Has that actually happened? Since Docs.SO went live, have we seen any change in the number of questions being marked as a duplicate? Similarly, what are the numbers on Docs.SO citations, particularly relative to citing other SO posts? Have they changed over the last few months? Commented Dec 12, 2016 at 7:06
  • 56
    Documentation honestly feels like it fell victim of what it was trying to prevent. Its initial goal was to make documentation for languages that lack it, but - in my personal, very subjective opinion - the reputation gains ruined everything. As soon as you start giving rewards for something that might already exist somewhere else you can bet someone's going to milk that instead of making something new and original. I have a strong belief that while there's any reputation to be gained from Docs it will fail to serve the purpose it was built for.
    – SeinopSys
    Commented Dec 12, 2016 at 9:42
  • 11
    I love the concept of Documentation by example. And when I was contributing I tried to focus on creating a code snipped that would work as soon as possible after pasting it into an editor. I think this is what Documentation project should focus on, rather than syntax description.
    – lonelyelk
    Commented Dec 12, 2016 at 10:49
  • 14
    @Nicol Bolas: That reviewer has given "557 non-wiki answers with a total score of 692." I don't know C++, but based on my experience with the [c++] tag, that sounds like a really abysmal ratio. I'm not particularly inspired by them holding a silver tag badge. (And that's why I don't think awarding documentation privileges based on tag badges works, or scales, well.)
    – BoltClock Mod
    Commented Dec 12, 2016 at 11:38
  • 13
    I stopped reviewing Documentation when I found that I couldn't flag anything. People can copy-paste official sources and Wikipedia to their heart's content, it gets robo-approved, and the only way to stop it is custom mod flags. It needs much better quality control. Commented Dec 12, 2016 at 16:03
  • 10
    @S.L.Barth I guess the review process as always been an issue on the main site, I don't know why we thought it would magically be fixed in the documentation reviews. Commented Dec 12, 2016 at 16:22
  • 18
    I still don't understand what Docs is supposed to be, so I can't really judge it for success/failure. Commented Dec 12, 2016 at 23:34
  • 42
    A couple of things I want to add - I mentioned this before. Get rid of rep on documentation immediately. I mentioned this in the initial beta. The people who want to write good docs don't need any rep. The people who don't know how to write docs want all the rep they can get so they will do anything to get it. NO INCENTIVE IS NEEDED FINAL. My second point is the documentation tab is not welcoming. Its rather poor and static. It needs to bring the user in...read some articles on things like faceted navigation / search. Right now the UI is very dull and non welcoming.
    – JonH
    Commented Dec 13, 2016 at 17:18

9 Answers 9

190

Is this a common trend for the whole docs?

It definitely seems like most experts have given up on it. Most posters that are still active seem to have poor to average knowledge about the topic and therefore write sloppy or incorrect articles.

Instead of becoming the canonical documentation over a certain tag, Documentation has now turned into a random dump of "this is cool", "this is a fun trick", "teh codez". Not to mention countless duplicate posts.

(Have a look at for example the C++ Documentation - I don't know if I should laugh or cry. For example, go look for info about the const keyword and const-correctness and you shall find at least 5 different categories about the same thing. None of them named type qualifiers, which would be the correct and formal category name. I would imagine this is because Average Joe has no idea what a type qualifier or a qualified type is, so he makes up his own category "stuff about constant variable things".)

Personally I stopped contributing pretty much immediately, because of the low quality, the lack of organisation and the lack of policies. So much crap was posted that the whole thing quickly went far beyond repair during the very first week.

At this point there is nothing that can be done but to either nuke all Documentation contents and start over with much stricter rules, or to ditch the whole project and move on.

20
  • 41
    Very clear diagnostic, 100% agree with all of this.
    – ken2k
    Commented Dec 12, 2016 at 15:56
  • 34
    This. Documentation should have never existed. It seemed a bad idea when it was proposed, it sucked when it launched, and still is the same crap. Burninate it!
    – Oriol
    Commented Dec 12, 2016 at 15:57
  • 77
    As the [css] top user and [html] number 2, my comparison of their Documentation tags to W3Schools ("W3Schools is better") holds true. Half of them are mediocre attempts at examples, the other half are attempts at copying official or other third-party docs while still somehow managing to get things wrong. How can people - in plural, collaboratively - make something that's worse than the already notoriously bad W3Schools?! I honestly don't remember the last time I approved an improvement request that added content rather than deleting it.
    – BoltClock Mod
    Commented Dec 12, 2016 at 16:12
  • 13
    This is exactly how I felt after a week or so of contribution, and hence stopped.
    – Oleg
    Commented Dec 12, 2016 at 16:32
  • 1
    @BoltClock To be fair(ish) that metric might be metered a bit by the fact that silver-badge holders don't need a review process to make edits. So you don't necessarily review (m)any high-quality edits/additions, by design.
    – TylerH
    Commented Dec 12, 2016 at 17:19
  • 3
    "None of them named type qualifiers, which would be the correct and formal category name." However correct and formal that name would be, you still have to know that's where you would look up info on const. And quite a few C++ programmers don't. So such an organization scheme is utterly useless to them. Docs.SO should not look like cppreference.com. And that's fine. Commented Dec 12, 2016 at 17:20
  • 34
    So can we now declare documentation to be dead officially? As an expert, I waited for exactly that, so that we can now start over and focus on quality this time…
    – Bergi
    Commented Dec 12, 2016 at 18:15
  • 4
    Pedantically, "type qualifier" is C terminology. In C++, it's a cv-qualifier.
    – T.C.
    Commented Dec 13, 2016 at 18:02
  • 2
    What if there were elections (or at least required recommendations) in order to contribute to docs? If the people allowed to edit docs for a tag begins with a small number of quality users and the recommendations to add to the group are reviewed by at least a couple other people in the group with adequate controls on that review process, it could grow organically to include only quality editors/edits. Docs for a subject don't need 30k people to create them. 1k or even 200 users who have the time to invest could produce something wonderful. Different than SO, but maybe Docs will work different Commented Dec 13, 2016 at 20:25
  • 4
    SO is basically a many-to-many system. Docs is a many-to-one, many times over. What worked great for SO appears not to work for Docs. Wikipedia is similar to what Docs sounds like it wants to be. Perhaps the solution was over-engineered with an everything-looks-like-a-nail approach. What about a reboot starting with something closer to a basic wiki. Commented Dec 13, 2016 at 20:30
  • 1
    @jinglesthula "What about a reboot starting with something closer to a basic wiki." Good idea. May I add an "let's take the most famous questions from Q&A" and let's rewrite them in form of a Doc topic as an exercise. Commented Dec 13, 2016 at 21:57
  • 27
    A core issue is that answers on Q&A can be a finished product in (usually) a few minutes. Docs for a topic need to be architected. That is not a labor allowed in Docs today. It's current designed incentivizes small drive-by edits without regard to the structure of the whole. The best documentation projects on the web are characterized by a good organization as much as by quality atomic pages/examples. Commented Dec 13, 2016 at 22:35
  • 13
    @jinglesthula: "The best documentation projects on the web are characterized by a good organization as much as by quality atomic pages/examples." This cannot be underestimated. In most cases, the difference between good documentation and bad documentation is not the content of information, but how well organized it is. Docs.SO's exceedingly flat hierarchy of "Tag/Topic/Example" is a terrible way to organize information, one which causes redundant information and makes it difficult to find anything. Commented Dec 14, 2016 at 15:49
  • 8
    @usr1234567: And that's the difference between Documentation and SO. With SO, you have a problem, you Google a solution, you move on. Documentation, good documentation, is not something you move on from. It's like a good book on history or Wikipedia. You don't just find out what happened on such-and-such a date. You find out why it happened. You walk from section to section, learning new related things as you like. You can learn, not just how to solve an isolated problem, but how a system actually works. Good categorization and organization is essential to that. Commented Dec 14, 2016 at 21:14
  • 4
    @NicolBolas Documentation is not something you move on from - I completely agree with this post and was excited when Documentation started because I hoped this would be created. Then it turned into "Examples" and immediately saw contributions turn into the "Google will find your code to copy & paste" form of one-shot examples. If it is and stays examples - IMHO - it is impossible that we will see good documentation or anything besides "give me the codez" Commented Dec 17, 2016 at 12:43
70

Is Documentation failing?

I think it is. Take for instance one of the top 3 tags, the C# one.

The number of topics didn't change for weeks. The activity tab shows no update at all for the past 2 days, barely some additions for the past week, the majority being done by a single or two people.

I don't even talk about the quality of the last additions.

Once the initial easy-to-win reputation has been earned by users, almost no one else appears to be contributing anymore.

29
  • 8
    They had a lot of attention in July/August when the idea was fresh. If only the system had been more mature then.... Maybe they just went public too early but then how do you make the necessary experience to correct your errors without spoiling the fun for the audience? Also: Not sure what activity would be expected? Surely less than in Q&A. In Q&A there is a lot of duplicate questions, while a wiki-like approach will saturate at some point. So we should not compare activity with Q&A but rather with other documentation systems. How much daily activity is there for MDN or cppreference? Commented Dec 12, 2016 at 12:08
  • 1
    "..almost no one else appears to be contributing anymore." And since contributing content is the one thing StackOverflow cannot provide by themselves, the question is, why. My speculation would be (in case it truly fails) that the framework (rep, the structure, the organization) just wasn't what people expected. I would still kind of believe in the example-centric documentation idea. But it also might be that just not enough people believe in the existence of good enough examples. Commented Dec 12, 2016 at 12:18
  • 3
    @Trilarion I don't think one should compare some community driven content such as Documentations, with other documentation systems such as MSDN. On MSDN, once a new framework version is released, the huge pile of new doc that is associated with new features is added. You wouldn't expect constant additions over time, more punctual additions when new products are released. On the other hand, for something designed to be built by the community, if you don't see any new addition in a while, then just like for any other community-driven project, it's kinda dead.
    – ken2k
    Commented Dec 12, 2016 at 15:49
  • 11
    @Trilarion As a side note, as a gold C# badge owner, I can tell the C# documentation is (really) far from perfect as of today, so no activity on it is definitely not a good sign...
    – ken2k
    Commented Dec 12, 2016 at 15:50
  • I totally agree that it is not a good sign. Maybe the experts are just waiting to see what the StackOverflow team will make out of it regarding the framework. All that would be necessary are a bunch of experts feed up with answering duplicate questions on Q&A all day long and willing to build up a canonical catelogue of good examples and there you go. They could coordinate with a thread on meta and wipe everything they don't like (deem useful) and create what they want using all the tools. Maybe this is by itself not an interesting task, or it is too complicated or... Commented Dec 12, 2016 at 20:19
  • ... or the framework is just not the right one for the task, then Documentation will fail. But my guess is that every moment someone could go out and change something in Documentation. It's kind of usable. StackOverflow failed to deliver a really good system at the beginning of the public beta and therefore wasted a lot of good will, but they also modified their course. If you would see it now for the first time, would you use it? Commented Dec 12, 2016 at 20:23
  • 9
    @Trilarion you are a glass-half-full person. SO.docs has already failed. There is nothing that can save it. There were fundamental flaws built into an inherently poor design of a product that's ill intentioned, cynical and conniving. Sometimes this recipe of traits and exploitations is successful, like Facebook. Most times it's not. The originators of the idea went a little too far in their desperate attempts to extract time and coin from their audiences, this time. It has had a negative effect on all of SO, too. Kind of like Google Glass.
    – Confused
    Commented Dec 12, 2016 at 23:07
  • @Confused Maybe, maybe not. I don't think it's really evil. Other things are but this? It's mostly the design that's not fitting. Commented Dec 13, 2016 at 8:11
  • 4
    @Confused Okay, but what do you propose to do? Celebrate the failure of Documentation? Create a better Documentation somewhere else? Contribute further on StackExchanges. Boycotting StackExchanges? If the Q&A part dies, I would be quite unhappy, if SO Documentation dies... I wouldn't care much. Commented Dec 13, 2016 at 11:26
  • 7
    @Confused I'm not sure exactly why, but it seems like you're calling SE evil and greedy for making a bad feature. Seems like it'd be more constructive to either help them improve it (because they're just devs like us) or to walk away. No point in calling into question their moral character. Commented Dec 13, 2016 at 17:47
  • 5
    @Confused - I can agree on some points you've made but you are borderline going way into the too nuts zone. If we take your advice there wouldn't be anything tried, tested, and failed / succeed. There are a LOT of products at google that fail...but that doesn't remove the fact that there are lessons learned here. Lessons learned can come handy much later. So considering you have no money invested in docs you need to relax and understand that sure it might not work but the lessons learned may be very good to have in the future.
    – JonH
    Commented Dec 13, 2016 at 21:06
  • 3
    So I propose, @Trilarion, that everyone accept SO.docs has been damaging to SO.Q&A, damaging to the SO brand, a complete failure, and learn from it... and burn it to the ground.
    – Confused
    Commented Dec 13, 2016 at 21:20
  • 5
    @Confused: Docs.SO is crap, but I wouldn't say that it has damaged Q&A in a significant way. It has led to the granting of a lot of un-earned rep, but that can be nullified by just removing that rep. SO's brand isn't harmed, since Docs.SO is just an add-on, rather than being fully integrated into the system. It is a failure, but hardly brand-damaging. No more so than that Task thing they tried out. Commented Dec 14, 2016 at 15:53
  • 3
    Task? You mean Teams? That didn't make it so far. Come to think of it the developer story is kind of crappy too. I would say eliminate all of these initiatives and stick to your roots of Q&A. That is what you are good at.
    – JonH
    Commented Dec 14, 2016 at 16:57
  • 1
    @Confused: "You're one that persisted" ... I have? Oh sure, I've made a couple of edits to a topic or two recently, but that was only because I was looking at the C++'s tag (the SO one, not Docs.SO) and saw that the topic count had increased. So I wanted to see what garbage someone had added. I would not consider myself to have in any way "persisted" with Docs.SO. Commented Dec 14, 2016 at 21:42
58

I asked for metrics in the comments; the suggestions I got were links, activity, and views.

Linking and activity:

Month      InterLinks ExtraLinks MinorEdits MajorEdits Topics Examples ProposedChanges ImprovementRequests TopicRequests Votes 
---------- ---------- ---------- ---------- ---------- ------ -------- --------------- ------------------- ------------- ----- 
2015-12-01 1          null       40         145        13     71       177             19                  3             112   
2016-01-01 3          null       36         205        34     86       183             32                  null          102   
2016-02-01 null       null       50         233        24     101      234             35                  1             163   
2016-03-01 6          null       99         689        126    351      640             194                 8             327   
2016-04-01 33         null       254        1197       216    617      1102            210                 11            610   
2016-05-01 6          null       44         131        18     59       151             25                  1             84    
2016-06-01 10         null       144        528        65     301      502             88                  8             433   
2016-07-01 560        363        7870       24390      3248   11653    29605           6243                1063          29228 
2016-08-01 349        586        2538       6035       802    2926     10966           2066                531           12402 
2016-09-01 291        344        1577       6971       1244   3313     4937            932                 347           6430  
2016-10-01 137        329        741        2469       444    1128     3263            620                 174           4924  
2016-11-01 109        286        673        1525       242    652      2631            374                 137           3640  

graph of the numbers above

Views:

As with Q&A, I don't have a particularly good way of tracking views over time... So here's a graph from Google Analytics:

google analytics page views - take with grain of salt

As with the activity graph above, this suggests an initial spike in activity when Docs went public, followed by a gradual fall-off over the next couple months.

Folks with the site analytics privilege can compare the shapes here to activity on Stack Overflow and other sites in their early days.

11
  • It's not clear how much the total number of Links, Topics, and Examples is developing because possible deletions of links, topics, examples are not listed. Do they play a significant role? Commented Dec 12, 2016 at 20:33
  • I just ignored deleted things for the purpose of this post, @Trilarion; at this point I think they'd be more of a distraction than anything. A year on, might be more useful to consider how deletion plays into activity.
    – Shog9
    Commented Dec 12, 2016 at 20:35
  • Since you cannot count views over time, perhaps you could just give a snapshot of total views for the top 10 (or more) tags?
    – Travis J
    Commented Dec 13, 2016 at 0:54
  • 1
    select sum(ViewCount) from DocTopics -> 563091 @TravisJ
    – Shog9
    Commented Dec 13, 2016 at 0:58
  • 33
    I don't think "gradual" is the right word for that drop off...
    – skrrgwasme
    Commented Dec 13, 2016 at 17:55
  • 5
    August-November is pretty gradual, @skrrgwasme. You gotta ignore the spike, since tons of folks jumped in during the first week just for the novelty.
    – Shog9
    Commented Dec 13, 2016 at 17:57
  • 7
    @skrrgwasme If these were the usage numbers of my app on the Android marketplace I would start worrying. Most of the folks visiting in August never seem to have come back. Commented Dec 13, 2016 at 22:02
  • 2
    >50% drop off in one month - July. That is not gradual. August and Sept maybe. but not really them either. Commented Dec 22, 2016 at 0:43
  • 1
    4500% increase in one month - July. Flash-in-the-pan excitement over a public beta shouldn't be given too much weight, @Michael.
    – Shog9
    Commented Dec 22, 2016 at 2:13
  • Perhaps it's the lack of recovery that should be given some weight. How do those numbers look compared to SO's?
    – Rob Grant
    Commented Jan 15, 2017 at 17:03
  • 4
    @Shog9 Would you be able to update the graph until 01 Feb 2017? Let me know if I can help you with that.
    – Oleg
    Commented Feb 17, 2017 at 13:00
48

Well, motivated by this post, I dove into the Java documentation and... wow. The first post I even read has blatantly wrong information (it said that an ArrayList resizes without overhead - which is ludicrous, as seen in the ArrayList source code.)

If something like that managed to get through on one of the most common languages, then there is little hope for Documentation in its current state. Four? people approved the original, wrong post. At least, I hope that four people approved it. For a badge holder to approve it would be even worse.

My correction was approved pretty quickly, but still... I don't have the time or motivation to go through and check everything, and it's clear that nobody else did either.

-- since the post mentions reputation

Docs are far too fluid in authorship to properly assign main SO rep.

With the exception of community wiki stuff, questions and answers are owned. It is also not acceptable to change answers and questions from the OP's original intent, even if the OP is wrong.

Docs have no such element of ownership - nor should they - and therefore the normal rep system is impossible to tune for them. Rep whores aren't the problem - the problem is that we're trying to assign rep for a contribution which can't be owned in the normal SO way.

7
  • 19
    The issue with information accuracy is two things: 1) it's way too easy for people to insert poor information, and 2) the people who could recognize it don't use Docs.SO frequently enough to police it. Commented Dec 13, 2016 at 18:25
  • "...we're trying to assign rep for a contribution which can't be owned in the normal SO way." We kind of could if we wanted to. For example by not only passing or rejecting edits in the review queue but also by rating them there (major/minor) and then blaming the outcome and distributing rep by line or something else... But I totally agree that it would probably be overkill. Once one realizes that rep is totally virtual anyway, the question remains where the motivation for contributing to Documentation should come from. Commented Dec 13, 2016 at 18:27
  • 1
    @Trilarion I agree that there are ways to try and assign rep and that rep isn't the best long-term motivation, but what you've described is definitely not the 'normal SO way'.
    – Jeutnarg
    Commented Dec 13, 2016 at 18:40
  • 3
    I especially can't be bothered to clean up the Java SO Documentation because the official Java documentation (both the API docs and the Java Tutorials) are already great. It would be a tremendous amount of work just to attain parity with the officials docs, for no real gain. Commented Dec 13, 2016 at 22:29
  • 1
    Aside from the two issues that Nicol pointed out, the real problem with information accuracy is the reviewing qualifications. That said, your example is, in my opinion, not an especially good one. The original text didn't say that resizing was free, it said it was automatic, which is true.
    – Cody Gray Mod
    Commented Dec 14, 2016 at 2:07
  • Considering that 'automatic' was used immediately after saying that copying arrays is inefficient (especially since the only named List implementation, ArrayList, resizes by copying) and in a section titled 'A better alternative to array resizing', I interpreted 'automatic' to imply that this resizing was with no overhead, or at least reduced overhead, as I believe most readers would have. Out of context, 'automatic' was correct, but in context it was not. Perhaps the author actually understood things and just messed up the structure. We can only read the text, not people's minds.
    – Jeutnarg
    Commented Dec 14, 2016 at 7:20
  • @NicolBolas that's why I proposed meta.stackoverflow.com/q/330049/248058
    – Knu
    Commented Dec 14, 2016 at 23:23
31

Is Documentation failing?

Maybe. It's probably a bit too early to tell.

(Warlords of) Documentation was meant to be an example centric approach to Documentation including unicorn points. It features tags, topics, examples, votes on examples, requests, reviews and now also discussions.

Activity was very high at the beginning of the public beta with a strong decline which is quite typical for many new things. Now we are in consolidation phase with rather low activity. Interest could pick up or the idea could die slowly. Time will tell.

So far activity is not zero. Let's take another tag, let's take the Android tag and you see multiple modifications per day. Is this too low? I don't know. You would have to compare with other documentation systems.

The Stack Overflow team showed commitment to improve Documentation. There are regular updates and new features. For example they greatly lowered the rep gains. So at least there is ongoing technical support.

Documentation does not seem to be extremely popular with search engines but that may be kind of expected given the age and the quality of the content (I experimented a bit and google seems to currently prefer other more established sources of documentation).

The true questions are:

  • How high is the quality of the content currently?
  • Is the system capable of delivering high quality content at least in the future?
  • Is example centric the right idea?

I'm not convinced of that, but currently I'm also not convinced of the opposite. I'm just waiting and watching it. I'm only sure that if high quality content is there, search engines will eventually list it prominently.

Summary: A fair estimation is that probably no-one knows if Documentation is failing. It might be too early to tell. Stack Overflow team members should have more information/statistics, which maybe they want to share? Anyway, the only thing that is sure in my eyes, is that Documentation so far is not an overwhelming success. There were strong critical points always mentioned and the stance of Stack Overflow was as far as I remember that some things in life you have to try out.

So far, Documentation is not a success.

3
  • 5
    I think that example centric idea is the main thing that majority of SO visitors are looking for.
    – lonelyelk
    Commented Dec 12, 2016 at 10:59
  • 4
    @lonelyelk But still even with examples at the focus you can still fail by for example making examples hard to find, or making examples about topics no-one needs, or making trivial examples. Commented Dec 12, 2016 at 12:03
  • 3
    true that. But almost all examples I find with google in SO Q&A are useful. I guess it would be great if Documentation examples could do that. Hard to say if it is achievable though.
    – lonelyelk
    Commented Dec 12, 2016 at 12:51
9

It was a fun beta, we now know what to expect of the system and its users. Now tweak some variables (reputation needed to participate, reputation needed to approve, vetoing and rollback rights) and implement what has been missing from the start:

Discussion / Talk

It was about the first thing I asked for in the closed beta, and I haven't seen it implemented in the year following it.

If you can't coordinate with your fellow users, if you can't explain to current and potential contributors what the documentation for a given tag is supposed to look like, the only thing you're going to get out of it is people throwing mud against the wall and seeing what sticks.

So implement that, archive all existing documentation and start over.

See also:

6
  • 4
    This is being implemented right now, FWIW; not trivial.
    – Shog9
    Commented Dec 13, 2016 at 16:32
  • 5
    @Shog good to hear! I'll be visiting docs every 6-8 days until it is implemented.
    – CodeCaster
    Commented Dec 13, 2016 at 17:14
  • 11
    I think we're missing something more fundamental than discussion, and that's a vision of what the purpose of Documentation is. Who's supposed to use it, and how? What niche does it hope to fill that existing official documentation doesn't provide? Are readers expected to arrive via Google? How? Q&A is easily Googleable, but subsections in structureless, broadly-titled documentation topics are not. Do we want them to navigate the Documentation interface to find what they want? They won't; it's clunky and confusing. We haven't been given a single user story from a reader's perspective yet.
    – Mark Amery
    Commented Dec 13, 2016 at 21:24
  • 4
    @Mark I do agree with your points, but I think the vision for Documentation is quite clear: provide documentation, along with examples, for code (frameworks/libraries) that has none. This is quite the opposite of what is currently happening, being everyone rewriting M[S]DN in their own interpretation using "user-friendly" terminology that causes confusion and errors. A clear intro for editors of a given tag/topic to explain what is and isn't on-topic will help a great deal there. I envision power users who can discuss and determine a policy and enforce it, but that's perhaps for a later stage.
    – CodeCaster
    Commented Dec 13, 2016 at 21:49
  • 2
    I think you meant 6-8 weeks, @code.
    – Cody Gray Mod
    Commented Dec 14, 2016 at 1:59
  • 2
    @Cody Gray: Nah, CodeCaster is just so pumped for these changes that they're willing to check back every week even if it actually takes them 6-8 months to implement.
    – BoltClock Mod
    Commented Dec 14, 2016 at 5:43
-18

I have read all above answers, so I am sharing my view which is helpful for moderators to take decision on Documentation topic.

I love documentation feature
I read documentation topics daily to enhance my knowledge.It is not like book examples, there are written by developers so you get more industrial knowledge. Recently I added some examples in documentation and also linked them with my answers. Android has most topics and I am lucky to have Android developer position. Even I have sent email to StackExchange to apply this documentation feature on CodeReview site too.

Should we remove reputation gaining through Documentation? No
I am happy to learn from documentation but I will not create new topic or improve a documentation topic until somebody motivates me to do it. I am giving time to something and if I do not get any feedback/reward, I will be passive. I have seen some topics where 10+ members have edited it and it's quality is best.

What is missing? or How to improve it so that it can reachable to most users.
Most of the users navigate to StackExchange sites through Google or other search engine results. But in case of Documentation, I have not seen search engine result navigation. Even if I tried to search with exact topic name but got no result link to Documentation.

4
  • 8
    I am personally glad that Documentation has not yet been indexed by google, or if it has it has ranked it low. There is much misinformation being provided by misinformed users with very little comparable oversight from informed peers.
    – user4639281
    Commented Dec 16, 2016 at 7:43
  • @TinyGiant but when more people reach to it, they can improve the content. ThinkPositive Commented Dec 16, 2016 at 8:33
  • 9
    @HarishGyanani We need quality, not quantity. At the moment, quality control in Documentation is terrible. I strongly oppose getting even more people in. First fix the quality control. Commented Dec 16, 2016 at 9:01
  • How do you know everything there is written by developers? They're not even the only ones posting answers. I prefer highly upvoted answers that are either backed by trusted sources directly or that can be done so manually.
    – Jamal
    Commented Dec 19, 2016 at 20:14
-24

Failed, is the answer to your question.

You don't need stats to see this. Some things are obvious.

TL;DR When folks with a puerile love of crafting, implementing and enforcing rules apply themselves to building a creative platform (as opposed to a responsive framework built on and of inherent imbalance), the shit hits the fan.

Google Glass was fundamentally flawed in a similar manner. It failed to understand the needs, desires and concerns of its audiences.

Potential users weren't happy about the pricing, nor that it was being rolled out as an endlessly uncertain beta in an obvious and failed attempt to obscure the uncertainty of its direction and purpose, and the compromises inherent to its conception, execution, design and implementation.

Further, these first class users, expected to pay the price of their time, cash, reverence and reputation to support and promote these devices were also expected to develop content for the platform. The expectations and desires of the platform are simply too high and stink of hubris.

Similarly, those best equipped with the wisdom and insights required to give great explanations of suitable demonstrations, samples and examples were flummoxed by the equivalency given to people with near no ability beyond press-record, copy/paste and exploitive desires.

Those potentially in front of someone using Google Glass were uncomfortable with the uncertainty of a camera being pointed at them, all the time, and not being able to ascertain its state or activity of the user. This is somewhat akin to not knowing the experience, wisdom, sources, insights and motivations of those "creating" SO.docs examples, nor any meaningful criticims of the content existing.

Despite considerable astro-turfing, the observations and criticisms of legitimate commentators and thinkers that Google Glass and SO.docs were fundamentally flawed in design, intention and execution rang truest. That nobody in a decision making capacity took these genuine concerns and criticisms seriously speaks volumes for the decision making process.

You can't regulate good behaviour: a culture, community and belief system must be created, cultivated and curated that promotes it. Most people have an innate understanding of this, except for one very special group of people: misanthropes. Their peculiar view of the world sees them thinking there can never be enough fascism and there's nothing wrong with any form of legal exploitation. This odd contradiction fits their peculiarly irrational logic perfectly, as they side with themselves against their own species, with the rules against humanity's best aspects.

Google Glass comes from this perspective, as does SO.docs

18
  • 10
    On the face of it, similar equivalency would obviously seem to apply to Q&A, which was built by essentially the same group and has similar values of equality. This post completely fails to differentiate these, then compounds this by making unsubstantiated accusations of astroturfing, misanthropy, and fascism. (In particular, suggesting that any time some organization fails to consider criticisms adequately, it's because misanthropes are in power, is at once staggeringly misguided and remarkably unhelpful in avoiding such mistakes in the future.) Commented Dec 13, 2016 at 1:10
  • @NathanTuggy I'd like to draw your attention to the part you missed, about SO.Q&A: "(as opposed to a responsive framework built on and of inherent imbalance)" Your other comments seem to fall inline with the degree of obliviousness required to miss this obvious reference.
    – Confused
    Commented Dec 13, 2016 at 1:20
  • 1
    Suffering from @NathanTuggy's myopia? You ask questions of Google, it responds. You ask questions of SO's community, it responds. These are responsive environments, inherently unbalanced because those asking don't know what they don't know, nor what the system/others know, or even how it'll respond. Within this environment there's sufficient imbalance to architect and orchestrate rules evolvement and enforcement. Google Glass, VR & documentation platforms require creatively motivated contributions for success. Google, Facebook and SO are good at rules in imbalance, not spurring creativity.
    – Confused
    Commented Dec 13, 2016 at 1:42
  • 9
    This seems like a long-winded way of saying that Google Glass and SO Docs are both a solution in search of a problem. It turned out that no one really wanted to wear a smartphone mounted on their head, and it turned out that no one really needs yet another place for documentation.
    – Cody Gray Mod
    Commented Dec 13, 2016 at 13:36
  • @CodyGray exactly, except I was hoping SOdocs would become the new, only place for docs ^-^ because SO rocks...
    – Fluidity
    Commented Dec 13, 2016 at 16:26
  • @CodyGray Imagine documentation having started with computing spheres that aren't well documented rather than saying "we're the new home for ALL documentation." Imagine if they'd realised the skills required to write good documentation are different than being good at asking and answering specific questions. Imagine they realised the ability to assess and edit documentation is an entirely different skill, too. Instead, their hubris lead them to focus in on what they wanted, merged with "if we build it, they will come" absent knowing who they are, what they need and why they do things.
    – Confused
    Commented Dec 13, 2016 at 17:12
  • @CodyGray Google Glass demonstrates Google doesn't really understand users of computers. It showed they had a clear focus on their own desires for computing's powers, and absolutely no idea what people wanted from an AR screen in front of them. We know Google wants Android, Search, Location and Image scanning EVERYWHERE, ALL THE TIME, and to give us ads based on what we see, where we are, who we're with, what we're doing etc. But what Page or Serg want isn't why people use computers and Google. SO.docs demonstrates SO's leaders don't understand writers, illustrators, readers and learners.
    – Confused
    Commented Dec 13, 2016 at 17:18
  • 2
    @Fluidity "I was hoping SOdocs would become the new, only place for docs ^-^" -- That would never work. The naysayers in the original Docs proposal Q&A covered many of the reasons why that wouldn't fly. Check the first half-dozen or so answers there below the very first one, as well as this one, which gets straight to the point.
    – duplode
    Commented Dec 13, 2016 at 20:16
  • @Confused: "Imagine documentation having started with computing spheres that aren't well documented rather than saying "we're the new home for ALL documentation."" That would change nothing. The reason that those "computing spheres" aren't very well documented is because there are not enough people to want to document them. Docs.SO could not change that, no matter how it was implemented. Furthermore, Docs.SO's example-focused documentation is very different from normal documentation. So even as a means of documenting less well-documented stuff, it would take some getting used to. Commented Dec 14, 2016 at 16:02
  • @NicolBolas the example-focused documentation "concept" isn't a good idea... at all, in its own right. I've not touched that aspect because its issues seem self evident, are compounded by the naming, and there's some semblance of recognition of this aspect of SO.docs problems. But let's look at your point: that there's not enough people in those spheres badly documented. Nope. That's not true. Apple's documentation is woeful, sparing, out of date and getting progressively worse. They're not the only high profile platform letting documentation slip. They're the norm. There is a need.
    – Confused
    Commented Dec 14, 2016 at 21:24
  • Rather than analyse and understand where needs are (for documentation), and what a better form of documentation may look like, SO.docs designers ignored common sense, dug a hole they thought they understood, to be filled in by people they presumed would come, for reasons they thought they knew. That's a string of fundamental flaws that are unrecoverable. Just burn it down, and think over, with fresh insight and a genuine compassion for all potential users. You know... like a product manager would do. @NicolBolas
    – Confused
    Commented Dec 14, 2016 at 21:28
  • @Confused: The reason that it is example-focused documentation is because the original idea SE had was that they would make a sub-site for examples. That it would be a curated collection of pre-built source code for doing certain things, not that people would consider this "documentation". That notion was added later, like some kind of tumor. So it's not that they "ignored common sense"; it's more that they started with one idea that mutated into something else, with neither part able to work with the other. Commented Dec 14, 2016 at 21:32
  • 1
    @Confused: "Apple's documentation is woeful, sparing, out of date and getting progressively worse." Then why haven't developers who work with Apple technology fix that? Four years ago, you could have said the same about C++ and its standard library. cplusplus.com was an OK site, but it was error-prone and slow to update. Then someone made cppreference.org, which is the go-to reference for C++ now. If Apple users were interested in making documentation, they would have done so with similar technology by now. How would SO having a docs site make them want to write docs? Commented Dec 14, 2016 at 21:37
  • TL;DR; they're competitive, rushing to make money as soon as they can, in the mad stampede that continues... unabated. They're still apprehensive about their future, not secure in it as C++ programmers are. And this is the case for many of the platforms and languages of programming. C++ programmers are the most (or second most) secure programmers. Plus, what you're showing only deal with a language, not the myriad of frameworks that are Apple, and not newness of language - Swift. This is a false equivalency. But your question of motivation is relevant. Bigger than this space, tho @NicolBolas
    – Confused
    Commented Dec 14, 2016 at 22:06
  • As to the original idea SE idea had... that's even weirder. That means they have no self awareness, and can't see their own impact on the zeitgeist of computing. Very odd. @NicolBolas
    – Confused
    Commented Dec 14, 2016 at 22:07
-27

Answering the question as a learning user of Python, Tkinter and Crypto: the documentation helps to narrow down the long searches in SO looking for the answer to simple questions you have while trying to develop an application. In SO the questions are almost always answered after difficult plowing to separate the many 'chaff' answers from the real one. I found in the Documentation many fast answers with good examples. What I think the Documentations is missing is the combination of some subjects examples into a single one; if not is falling into the danger of becoming a difficult search like SO. But Documentation helps! Keep it up!

9
  • 17
    Searching in SO is difficult because the team prioritizes things like the unikong game, rather than improving the search.
    – Oriol
    Commented Dec 12, 2016 at 16:02
  • 23
    @Oriol It's so true, we took 43 of our engineers off their projects for about 3 months and they did nothing but Unikong. We think it turned out pretty great though.
    – Nick Craver Mod
    Commented Dec 12, 2016 at 16:35
  • 4
    @NickCraver You should have put some of your marketing team on it too, I didn't know about the game yet and missed out on tons of fun :(
    – user247702
    Commented Dec 12, 2016 at 16:41
  • 18
    @Stijn Thanks, that's an excellent suggestion! We'll allocate at least 30% more resources next year.
    – Nick Craver Mod
    Commented Dec 12, 2016 at 16:43
  • 28
    If you're using the Stack Overflow search, you are categorically doing it wrong, except in certain special cases where you really need features that only the SO search can provide. (Hint: you don't.) Use Google. They mastered the search business a long time ago. Constrain it to site:stackoverflow.com if you want, but it often isn't necessary. You don't care if the answer you find is on SO or not; you just want the answer.
    – Cody Gray Mod
    Commented Dec 12, 2016 at 18:43
  • 6
    To add to @CodyGray's comment, if you want StackOverflow answers to show up on the top of your google search, just type "StackOverflow" at the end of your question. I do this all the time and Google automatically moves the SO answers to the top. This is way better than just searching SO since, believe it or not, once in a while SO might not have an answer to your question, yet a different site does. Sometimes this is even another StackExchange network site.
    – Tot Zam
    Commented Dec 12, 2016 at 20:10
  • @tot I can't see why adding "stackoverflow" to the search query would be preferable than using Google's site: operator to constrain the search. You say that "once in a while SO might not have an answer to your question, yet a different site does. Sometimes this is even another StackExchange network site.", and while all of that is true, appending "stackoverflow" to your query seems like it would disrupt that the same as site:stackoverflow.com.
    – Cody Gray Mod
    Commented Dec 13, 2016 at 10:53
  • 3
    @CodyGray Because sometimes you find something not hosted on stackoverflow.com that is (at least remotely, for instance if the page contains a link to SO) about stackoverflow and will help you. For instance a bug report on Connect (with a link to a SO question), something on dba.stackexchange...etc. Plus, typing only "stackoverflow" is shorter. I personally do this all the time.
    – ken2k
    Commented Dec 13, 2016 at 13:33
  • 7
    @CodyGray site:stackoverflow.com filters the results to exclusively stackoverlfow answers. Typing stackoverflow at the end of a question just gives priority to the stackoverflow answers, yet also shows other sites.
    – Tot Zam
    Commented Dec 13, 2016 at 16:16

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