36

It's good to see Documentation beta in place. But still I am surprised on level of contribution from top experts.

e.g. https://stackoverflow.com/documentation/design-patterns/topics

I have seen more good examples in Stack Overflow questions than documentation topics. It's strange that momentum has not been picked up. Especially approvals to edits are taking a long time (sometimes more than 2 days) compared to editing of normal posts even for small changes.

It would be great if we know the methods used by Stack Overflow to bring top experts to contribute to the topics and make approval process faster.

15
  • 1
    Maybe true experts don't use beta versions ;) Maybe they will show up after the stormy beta phase has settled...
    – honk
    Commented Jul 25, 2016 at 16:09
  • 96
    We aren't contributing because the interface is asinine and hard to follow. Links are everywhere, text is everywhere, the sort / group mechanism is confusing, the blue led dots are horrendous, the bad crap that is being suggested or put into documentation is just that crap, the newbies who post horrible questions are posting horrible documentation. I mean just look at the sql and C# documentation - need I say more? Where were all the beta testers before this release? I don't remember seeing meta posts of issues or problems related to the UX and its choke full of UX issues.
    – JonH
    Commented Jul 25, 2016 at 16:16
  • I'm not sure what that example is meant to show. Take a look at Java; 157 topics + 20 topic requests. JavaScript is going pretty strong too. Design Patterns are pretty well documented elsewhere, so it could be that experts feel there doesn't need to be more docs about it. Commented Jul 25, 2016 at 16:24
  • 11
    @JonH: " I don't remember seeing meta posts of issues or problems" The private beta site had attached Q&A that they used for Meta stuff like that. This screenshot shows such a question. It would have been frankly aggravating to have questions about a private beta here on MSO.
    – jscs
    Commented Jul 25, 2016 at 17:19
  • @JoshCaswell - That's true enough.
    – JonH
    Commented Jul 25, 2016 at 17:20
  • 21
    The whole project is misconceived. Vendors and others with an interest in documenting their products adequately will either do so or fail inhe marketplace. Experts thrive by being experts, and have no economic interest in providing free documentation. The prior existence of job-interview question sites and any number of hobby sites which are all full of nothing but crap proves the point entirely. There is no reason for SO at contribute to that existing problem, or, as I have stated on a number of occasions on SO, to act as a validation site for arbitrary Internet crap either,
    – user207421
    Commented Jul 26, 2016 at 10:02
  • 2
    @JonH meta.stackoverflow.com/questions/tagged/… … a few … But TBH, as a developer it often is hard to figure out the own UX issues. Pointing them out is quite important for the developers.
    – bwoebi
    Commented Jul 26, 2016 at 10:10
  • 20
    @EJP Imagine in 2009: The whole idea of a Q&A site is misconceived. Programmers will either learn how to program on their own, or fail in the marketplace. Experts thrive by being experts, and have no economic interest in answering random bozos' programming questions for free. The prior existence of programming forums and any number of hobby sites which are all full of nothing but crap proves the point entirely. There is no reason to contribute to that existing problem, or, as I have stated on a number of occasions on SO, to act as a validation site for arbitrary Internet crap either. :)
    – Pekka
    Commented Jul 26, 2016 at 16:51
  • 4
    ... which is not to say I condone where Documentation currently stands. Just that the economic argument against it doesn't hold much water IMO.
    – Pekka
    Commented Jul 26, 2016 at 16:52
  • 4
    @Pekka웃 the thing is, that they weren't random bozos' questions, but their own peers questions. People they recognized and had respect for. The economic motivation still holds true if you consider who actually were the ones that started the movement.
    – Braiam
    Commented Jul 26, 2016 at 22:43
  • 4
    I'll not contribute until C#'s keyword goto is has moved to the end of the list. Commented Jul 27, 2016 at 7:41
  • 2
    @Braiam it was answering random bozos' questions from the moment SO left private Beta. I don't think that is arguable.
    – Pekka
    Commented Jul 27, 2016 at 9:59
  • @Pekka웃 I need to know the difference between random bozos' questions and questions you will feel glad to answer?
    – Braiam
    Commented Jul 27, 2016 at 17:16
  • 6
    @Pekka The situation in 2009 you mention is not in the least comparable and is not subject to any of the issues I raised. There were already quite a number of well-working Q&A sites in 2009, some of them of very long standing, and what elevated this one above them was not the novelty of the idea, but superior execution.
    – user207421
    Commented Jul 28, 2016 at 3:18
  • 1
    @EJP "superior execution" -> "at the time" -> of 2009, being the crucial component of context, most everyone will miss. Some still think SO's execution is as great as it was within that context. Quora, not having changed much, is slowly but steadily growing because SO isn't adapting to changing needs. Quora is now closer to what is a wider set of online needs for Q&A ... AND conversation. In 2009 Facebook hadn't become the web feeder it is now, programming still wasn't cool or considered more than a fad, and mobile apps were less than hints of what they've become. SO rules are digital fascism.
    – SKOOP
    Commented Aug 1, 2016 at 14:52

8 Answers 8

104

I can't speak for the reasons why experts don't contribute. But I can explain why my contributing to Docs.SO has decreased substantially since the start of private beta.

The #1 reason is that I don't feel like playing the part of Sisyphus, constantly fighting an uphill battle. That's what doing stuff in the C++ tag feels like. There's a constant deluge of poorly-conceived changes, topic proposals, and so forth to wade through. It's unending, and I don't want to deal with it.

A second reason is the difficulty of actually doing anything of note. Consider the C++ String documentation page. This page contains examples on everything to do with strings, from basic std::string manipulation to case conversion to find/replace, etc. The page has 17 examples on it.

Now, let's say that I wanted to split it apart into 3-4 separate topics. How would I do that?

If this were MediaWiki, it'd be trivial. I'd just create a few text files, copy the text from the topic, split each example out into the various topic-based files, and then submit them as new pages, submitting the now culled "String" page as a change to the current one.

With Docs.SO, the process is painful. Each example is its own text block, so you can't just copy-and-paste easily. Yes, there's a UI feature to break an example out into a topic. But to break multiple examples out into a topic, or multiple examples out into multiple topics? It all requires a huge amount of browser work, rather than just copy&paste in your text editor of choice.

And then, once you've made and submitted the changes, each change has to be approved. Separately. Even though logically, all of the topic edits are a single edit, each edit must be considered separately. So someone reviewing changes to the main Strings topic will just see a bunch of removed examples; they could easily reject it, not realizing (or reading the commit reason) that the data still exists in different topics. Someone might think that the new topics are duplicates of the existing Strings stuff, since that change has yet to be approved.

The system is optimized for dumping code wherever you want, not for putting existing dumps in the right place. So even if I felt like playing Sisyphus, Docs.SO makes his task even harder than it strictly needs to be.

So I think it's unreasonable to expect experts to bother. The large amounts of crap, combined with the difficulty of actually doing the cleanup, will keep them away.

5
  • 17
    Speaking of the terrible workflow, am I the only one that has noticed the page gets glacially slow and threatens to lock up my browser as I bounce around between editing the various examples? There's obviously nothing wrong with my computer, as no other page does that, but it seems to happen suspiciously often with Docs.
    – Cody Gray Mod
    Commented Jul 26, 2016 at 9:16
  • @CodyGray Not something I've seen, if anything, it seems pretty zippy all round for me.
    – DavidG
    Commented Jul 26, 2016 at 9:23
  • 1
    @CodyGray, I've seen it. It fully consumes a CPU core for many (10?-15?) seconds at various intervals (just enough time for me to switch to another task in another window). I have not timed it to see if it has a specific period. It only does it sometimes during editing. Other times during editing it does not. If it matters, I have only tried it with Firefox.
    – Makyen Mod
    Commented Jul 26, 2016 at 9:47
  • 3
    @CodyGray no you're not the only one
    – Liam
    Commented Jul 26, 2016 at 10:35
  • OMG, this. So much this.
    – eggyal
    Commented Aug 2, 2016 at 9:57
93

I tried Documentation last Friday and Saturday, and I have decided not to bother anymore.

The main problems I see are:

  1. The workflow is cumbersome if you want to provide quality content (eg requiring approval for stuff you are a (relative) expert in, not being able to improve contributions of others before approving)
  2. Posting in relative niche tags takes ages to approve (or a lot of begging around, which makes the review a farce)
  3. Total beginners in a subject (tag score 1(!)) post bad examples and get approved

    These examples are bad both in form and content, not adding value or even misinforming unsuspecting people reading it

  4. There is no curation (or at least it is very hard to do), topics and examples get created in general language tags instead of subject specific tags, topics get duplicated between language and specific tags (and even inside tags), a cancergrowth of similar examples

All this gives me the impression that either Documentation is low quality first, or it simply is unbalanced in its checks and balances, so it is spinning out of control.

All in all I feel I have better things to do with my time than to get frustrated about this. It has also made me reflect on my contribution on StackOverflow in general, and I'm not yet sure what the outcome will be of that.

1
24

I can say after I tryed Documentation that I don't bother anymore for the reasons that I yet spend multiple hours(!) on improving contents under the C tag (which is my profession) just to see not even 24 hours later all my efforts beeing eliminated by people that a) are skilled in C aswell but don't like what I wrote or b) have no clue and just want to get fast rep / don't get my point.

So listed bellow problems I faced so far when ever some quallified person tryed to improve it:

  • Improvement requests which contain a lot of detail about how to improve a specific example get "solved" by someone just deleting the whole example.

  • exhausting citation works of primary sources getting declared as beeing wrong by a single person. eliminating all the work done by a professional.

  • Minor typo fixes get far more often aproved than content changing proposals, where the latter gets automatically rejected as beeing in conflict, so the relevant edit has to be reproposed again and again. Not doing so for some hours makes the edit beeing out of scope soon.

  • No strict boundarys of what a document is expected to look like making change documents in a matter of a view hours expressing not so seldome diferent oppositions within just a few hours.

So for my self I can say I don't contribute to it anymore as what ever I contributed so far is wasted time since not a single letter of my 4 hours of time I investigated yesterday is available anymore. And this is just for reasons like a single person thought my work wasn't worth it, to contribute to the topic or because some one had a diferent idea of what the documentation has to be looking like. And as long there are nor straight policys about what something has to be like, why should I spent time in something that will just be available untill the first person reading it doesn't like or understands it?

1
  • 5
    Some of this sounds like how tag wiki edits get reviewed by people with zero activity in the tag. Unless reviewers with tag experience are very rare, it would be better to wait longer instead of having hard work rejected by people that don't understand it. And I totally agree that it's a huge pain to re-propose a change, since there's no mechanism for automatically rebasing a diff against the new version and showing you any merge conflicts. Commented Jul 26, 2016 at 11:07
18

The other answers focus more on practical issues, here I will share my personal experience which might point at problems on a different level.

Background: I consider myself to be a Matlab expert, who is now trying to improve his Oozie skills.

Situation: As soon as I heard of documentation, I decided to pay it a visit. First I visited Matlab, then I visited Oozie.

Experience in the matlab tag (From expert point of view)

At the time of writing there are 23 topics, so I decided to check out the most popular 20 as they fit on 1 page. Here I found the following:

  • 5x Trivial stuff, which appears to be in the documentation already (One of the topics is for loops ...)
  • 5x Broad topics, which are properly covered in the documentation, and get tiny coverage here that does not add anything (Image processing, which is a whole toolbox with proper documentation, is covered in 10 lines...)
  • 5x Complicated topics, These are probably covered in the documentation, but it may not hurt to read an explanation from a different perspective if one is going to work with the specific topics. At the moment I am not interested in any of these though, so personally I choose to move on.
  • 5x Things that are not covered in the documentation.

The last category is the most interesting one for me, so I zoom in on that:

  • Common mistakes and errors: Could be interesting, there is not much there yet though.
  • Undocumented features: This seems to be perfect for the site, there is not much there yet though.
  • Best practices: The topic has potential, but instead of having 1 or 2 sets of best practices, there are now two individual recommendations which take a whole post. As such the format seems ill suited. (I don't need 15 lines to understand that short lines makes code more readable)
  • Debugging: This one may be OK, though the part that is not in the standard documentation is very specific and not relevant for me.
  • Performance and benchmarking: This one seems OK

Honorable mention: Documenting functions actually contains an interesting contribution, but I believe that bit does not actually belong within that topic (perhaps it belongs in debugging).

Matlab tag conclusion: Most topics don't add to the existing documentation. Interesting topics are scarce, and typically not yet interesting in their current form.

After this I went to the Oozie tag, I will cover all topics as I only found 2:

Experience in the Oozie tag (From regular point of view)

  • Introduction to oozie: This is confusing, it first states "detailled instructions on getting oozie set up" and then proceeds with a remark on what kind of stuff oozie can do.
  • Oozie architecture: General explanation of what oozie is, do we really need this?

Oozie tag conclusion: There is nothing there yet. I registered for the tag but it hasn't moved in a while.

Overal conclusion and answer to why I have not become active on documentation

On stackoverflow, even in tiny tags, I tend to see interesting stuff which triggers me, and as such I may even contribute in this tag or another.

However on documentation, even if I look actively the signal to noise ratio is so bad that I just don't get pulled in.

2
  • 1
    There's even a section about plotting a sine wave in Matlab! It adds nothing to the existing official documentation. Nothing. Splitting lines with NaNs might be the only thing worth mentioning in the entire section about plotting. Commented Jul 27, 2016 at 12:04
  • The official MATLAB doc is so good and comprehensive that it's nearly impossible to add anything of value (except maybe for some very specific GUI stuff, and specific and localized problems are suitable for regular SO). I just don't see the point. Commented Jul 28, 2016 at 7:52
15

Something I personally find weird about the Docs is the approval process. With enough points on SO, no one needs to approve my Answers or questions.

So if I wish to add an example, why do I need to get reviewed? And anyone gets to review me, even those with 1 rep points? And 1 rep points also gets to create an example?

One of my examples took about 2 days to get approved. Some tags aren't active, and so with these tags, even if someone is knowledgeable in the field, and there's not enough traction on that section, an example can remain in the queue for a week.

What good is it writing examples that never gets approved nor no one gets to benefit from unless approved?

1
  • No one needs to approve anyone's answers or questions on SO: even unregistered guests can post Q&A. Edits to posts are another matter, of course—and I think documentation may have started from the standpoint that posting an example is effectively an "edit" to its topic...
    – eggyal
    Commented Aug 2, 2016 at 10:03
11

My issue or confusion is what about projects that have good documentation? I've seen examples that really copy and paste from good documentation so what is the value? It seems like a bit of a land grab from SO in these cases. An example of good documentation that springs to mind is Django REST Framework which is already open source and members of the community that care already contribute there - why duplicate the good work done on that project on SO?

The process has already started on the django-rest-framework tag. It looks like it's getting there but compare the amount of content in the DRF docs on serializers to what is on SO for DRF serializers. The process has started (and looks pretty good), and no doubt more content will be added but it's still the start of the process again.

I accept that it's possible that the two could be complementary because you get different perspectives on the development process but I'm going to go for the core project documentation pretty much every time, or spend time cross-checking SO with the project docs. The amount of work that goes into good documentation is massive - to see the process starting again on SO is off-putting.

I think in theory Documentation can work (certainly for tags with low quality documentation) but I'm intrigued to see how it works with existing high quality documentation.

1
  • 3
    If it's pure copying and pasting (with and especially without attribution), you shall remove that. There's no point in that.
    – bwoebi
    Commented Jul 26, 2016 at 10:23
10

The big thing for me is that starting to document an entire topic like x86 assembly language is such a big task that it feels like anything I could write would be a tiny drop in a huge bucket.

I thought docs.SO was going to be more like adding footnotes to existing documentation / guides / tutorials, but based on my limited poking around, it feels like docs.SO is designed for us to write a lot of stuff from scratch. I haven't tried linking "upstream" docs into docs.SO posts, though, so maybe something cool happens that I don't know about.

It would also be great if we could organize text from existing SO answers into documentation. I know I've written plenty of stuff in SO answers that would make useful documentation / examples for things. Copy+pasting it seems non-ideal, but maybe forking an answer into a doc is good. It would be good if there was a good way for bi-directional links to record this, so people looking at (or editing) the answer or doc could see the other. Having to edit a doc link into the question seems intrusive and noisy.


I like answering SO questions because there's a specific subject already given. That makes an interesting jumping-off point for pointing out interesting related things that the OP didn't specifically ask about.

An SO question is a bite-sized problem that you can solve and be done with. As long as you're sure your general idea is right, you don't even have to do the boring stuff like testing code that you write. (As long as your error rate is low enough that you're not constantly having to go back and fix things when people point out mistakes). It sometimes takes nearly 30k characters to write a fairly complete answer, but the fact that the end is already in sight when you start is what makes it enjoyable for me. (I literally have ADHD, so I think this part is a bigger deal for me than for the average person. ADHD is associated with being terrible at time management and getting started on large projects.)

Writing Documentation feels (to me) like starting in on the most extreme too-broad question. There's a zillion interesting things to say, but going into extreme detail about everything would make it hard for people to find anything (as well as taking forever to write).

2
  • 11
    it feels like we need to write a lot of stuff from scratch. do we really need to do that, though? Or is it being done just for the heck of it? That's my biggest tummy-ache with the entire thing right now
    – Pekka
    Commented Jul 26, 2016 at 10:53
  • 1
    @Pekka웃: reworded that into a criticism of (my experience with) docs.SO, because I agree we shouldn't need to. Commented Jul 26, 2016 at 10:55
2

One reason for slow turn-around might be what I suffer from - what does "Reject" do? I'm familiar with Flags and Close Votes on SO, but here Reject sort-of looks like Flag/Close, but sounds more drastic. Would I be better commenting? Have others votes to Reject, and if so, why? I get no feedback until after I commit my vote. Then once I finish, there is no button to move to the next change! Furthermore, there is no "Edit" button.

Another reason is that I review stuff and see multiple coding styles; what is the preferred style? Should I reject for being messy code? It's all just too different from what I am used to on SO.

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