2

Those of us who have been here for any significant length of time know all about Stack Overflow's struggle with quality.

When the Documentation beta first came out, I didn't really have much interest. I honestly thought that Documentation would become just another recycle bin. Consequently, I haven't really followed the Beta much.

But a couple of weeks ago, I trolled through a few articles. Boy, was I wrong about Documentation. The material there is spectacular; not only is it well-written and accurate, but it seems to hit the sweet spot of "material that is interesting because you can't really find similar material elsewhere on the internet, or in official documentation."

How did this happen?

More importantly, can it be sustained? What made the difference, and can that difference be preserved over the long haul?


Note: This isn't a criticism of Stack Overflow. Quite the opposite. There isn't a week that goes by that I don't find a useful answer to some problem there. But a repository of useful programming information is one of its stated goals, and there are clearly some weaknesses in this area.

32
  • 80
    What, Documentation is great now? Last week it was turning into W3Schools. I DON’T KNOW WHAT TO BELIEVE ANYMORE
    – Pekka
    Oct 2, 2016 at 18:00
  • 5
    I'm happy to be proven wrong. My experience with Documentation is admittedly limited; my first experience with it was in the C# tag. There's not much bad to say about that tag. Oct 2, 2016 at 18:00
  • 31
    I hate to also be a nay-sayer, but when I've looked over Docs in my fields of knowledge, I'm usually left with a resounding "Meh". I see a lot of poorly-written, unexplained, and/or overly-specific code interspersed with the occasional real gem. Basically, it looks just like the Q&A side to me. However, I'm interested to hear success stories from others.
    – jscs
    Oct 2, 2016 at 18:52
  • 17
    @Pekka웃 To be fair to w3schools, it's got a bad rep, in part, because it doesn't satisfy some software developers' sensibilities of pedantic perfection. Sure, it's not as accurate as MDN, but it's also easier to digest for a newcomer. We need resources like that; all too often we expect neophytes to run an Olympic sprint before we even teach them how to walk. Oct 2, 2016 at 23:40
  • 13
    I've seen a lot of content on Documentation that was blatantly copy-pasted from Wikipedia, or from the official sources of a product. That content is usually well-written, but I don't think that was the idea behind Documentation.
    – S.L. Barth
    Oct 3, 2016 at 6:42
  • 11
    @RobertHarvey I have no problem with their simplicity, I agree we need more of that. But they equipped generations of PHP newbies, for example, with actively toxic advice and code examples on how to connect to databases - which we here on SO then had to fix. Requests to change the code went unheard for years.
    – Pekka
    Oct 3, 2016 at 7:32
  • 11
    For me(a daily but normal user), documentation is like copy-paste code from boring site with no good example/information. Never clicked after starting days. Even your question get 3 dv with total of 8.. Oct 3, 2016 at 9:21
  • 7
    I submit into evidence stackoverflow.com/documentation/ruby/3464/comments which is pretty representative of the tags I follow. Oct 3, 2016 at 10:13
  • 4
    @RobertHarvey I'm in a ping pong club. While I've played a lot before joining the club, teaching myself with wrong material, some did not played a single ball before joining the club. Most of those are playing now a much better style than me since they learned the right moves just from the beginning while I'm struggling with changing my wrong style. To say in in your words: It's more likely that they will win the Olympic match than me :)
    – hek2mgl
    Oct 3, 2016 at 10:45
  • 5
    IMO the right move is to teach young programmers how to find and walk through documentation that comes from various sources depending on the software, which is usually the author of that particular product. Empowering a one-4-all, 3rd party solution that hides this process from young programmers is completely counter productive. Afar from that, I'm concerned how up to date a documentation which is not originated by the author of a product can be. And how much it will be able to address specific versions of a software. Let's see.
    – hek2mgl
    Oct 3, 2016 at 10:57
  • 24
    I hate to be a Doubting Thomas, but such a glowing review of Docs from a moderator (I support Docs and its mission btw; I'm not one of the naysayers) after pretty much only negative press comes off as a bit of a shill. Can you provide some links to the pages you have in mind as examples of 'spectacular, well-written', etc.? And perhaps let us know what tags you've looked at? e.g. only focused on C# or MVC, or if you've also looked at Java, Swift, PHP, JS, C++, etc.? Again, I want to give you the benefit of the doubt, but this is just such an isolated review, score-wise...
    – TylerH
    Oct 3, 2016 at 18:13
  • 12
    Your Experience Is Not Universal
    – user177800
    Oct 3, 2016 at 18:33
  • 6
    @TylerH: I'm not speaking as a moderator here, nor as a shill, but merely a user who had a positive experience in the C# tag. I'm aware that my experience may differ from those of others. As Jon pointed out, since there is no moderator tooling yet, I literally have no standing as a moderator in Documentation (though I now have renewed awareness of how people can interpret the diamond after my name). Oct 3, 2016 at 20:01
  • 6
    @JonEricson I don't have any prior reason to think of Robert Harvey as a shill or insincere at all in the years I've been here, but this kind of glowing reaction from any moderator in the face of what's largely been criticizing posts is just so out of the blue compared what I've seen posted that 'shill' came to mind for me and so I asked for some additional info, to be put at ease, for lack of a better phrase (which Robert has somewhat given now in his comment above).
    – TylerH
    Oct 3, 2016 at 20:07
  • 5
    you miss the point that I think @JörgWMittag makes, that is a completely useless piece of content and it tends to be very representative of most peoples experience with Documentation. Shovelware example rep farming. Rep used to mean "knowledgable" that is not the case anymore and getting the same rep for writing an example on comment syntax and say C++ Templates is the problem I think they were trying to illustrate. The best thing you can say about that ruby example is it is well formatted and is correct.
    – user177800
    Oct 4, 2016 at 17:17

3 Answers 3

16

How did this happen?

What you are claiming has happened has not happened as far as I (and others) can tell.

More importantly, can it be sustained? What made the difference, and can that difference be preserved over the long haul?

No, Nothing and No.

See also; Documentation is on its way to being the next w3schools

2
  • 5
    I see you've posted that link as an answer, as a comment on the question, and as a comment on the other answer. Oct 3, 2016 at 18:53
  • 3
    The only critique I'd say is that, with respect to the last questions, I'd be optimistic enough to say "nobody has figured it out yet" rather than, "it's impossible". I think it's still worth it to keep trying, even though nobody's figured it out yet.
    – Servy
    Oct 3, 2016 at 19:01
15

I think a big part of it has to deal with the context in which you approach what you want to write.

In Q&A you're first trying to answer a specific question, and you're doing that in the construct of whatever the OP has provided, which is usually code (or thinking) that simply doesn't work. There are constraints.

Documentation is more of a sandbox, you control the context in which you simply sit down and say this is what I want to teach. You can get much more inspiration when you're considering how to present an entire domain instead of explaining a tiny part of it, and you don't have to struggle as much to teach (or touch on) other requisite bits that would be needed in order for the OP to fully understand your answer. It just flows. And because of that, it's much easier to make cohesive and read well.

The other big part of it is the loosened sense of ownership. You might be a rather good writer, but not as strong in presenting informative examples that demonstrate how experienced folks are actually using things. Conversely, you might be great at cranking out really good code examples that strongly apply to common problems, but not so good at teaching people why they're good. The barrier to "just get in there and make it better" is lower, which I think makes a big difference, and is a big part of why it's looking to be sustainable.

Even the 'stubs' that aren't really all that informative or well-written turn out to be useful if they inspire other people to make something nicer, and again I think the loose sense of ownership is a big help here (folks can be reluctant to polish smelly things well if all the visual credit goes to someone else by way of the user card).

So I guess the tl;dr here is:

  • Fewer creative constraints. You don't have to make something fit within the context of whatever the OP posted, you can just sit down and teach.
  • A loose sense of ownership makes people more inclined to just get their hands in it and fix whatever needs fixing, even if it means major changes, because it doesn't feel awkward like it might in Q&A.

There might be other things at play, too - but these are the two that stood out the most for me.

21
  • 4
    Two good points. I believe a third point could be the "Reputation system". The gaming part of SO tend to require fast answers. Documentation allows the author to spend more time on writing. Oct 3, 2016 at 9:55
  • 1
    @4386427 yeah - I do sometimes wonder if a public rep system is a little self defeating in some regards. Fantastic for generating activity, not so good for generating quality...
    – Ant P
    Oct 3, 2016 at 10:44
  • 9
    "Documentation allows the author to spend more time on writing". I am still searching for original quality content in Documentation. Something we didn't have elsewhere. Oh, yes, maybe 1% which is even harder to find in the sea of pretty/clean/well written but useless stuff we have now. List of new C# 7 features? REALLY? Do we need it? Oct 3, 2016 at 15:20
  • 2
    @AdrianoRepetti If you're trying to figure out whether a piece of code you didn't write is compatible with C# 6, then yes, you need it.
    – jpmc26
    Oct 3, 2016 at 16:25
  • 7
    The problem (but it's not a shared opinion, it's obvious) is that the same information is available elsewhere. Not some obscure note, unknown blog or hyper technical article but msdn, and github.com. We should start to close one of them as duplicate! Oct 3, 2016 at 17:43
  • 2
    @jpmc26 nah, for that there's the source from where all that list was copied from...
    – Braiam
    Oct 3, 2016 at 18:35
  • 8
  • 2
    @Braiam Documentation produced by large organizations is rarely coherent enough to actually be usable. If you want to go by that argument, probably 80% of the answers on SO are replaceable with "official docs." We come here because the information is presented better and easier to get to what we need, not because it's impossible to find it anywhere else.
    – jpmc26
    Oct 3, 2016 at 19:11
  • 1
    @jpmc26 at that point you should ask yourself why the heck are we duplcating them, then...
    – Braiam
    Oct 3, 2016 at 19:21
  • 4
    @Braiam The users are doing it because they get Imaginary Internet Points for doing so. SO is doing it because it serves ads on that same content, and so gets paid for it.
    – Servy
    Oct 3, 2016 at 19:33
  • @Servy I'm unsure which of us is unsuitable to be member of SarcasmOverflow....
    – Braiam
    Oct 3, 2016 at 20:04
  • 5
    @Squidward are you sure? If I search for them I find C# 7 Work List of Features (which BTW is more up-to-date than documentation and there are MUCH more details) or even an introductory What’s New in C# 7.0. Feel free to compare with Documentation content. Oct 4, 2016 at 7:06
  • 4
    I read linked issues and for a work in progress that discussion is what you want (if you're interested to, of course). Are you interested in already stable features? New Language Features in C# 6. Same source, same quality. Do you need more? Pick Interpolated strings from MSDN. Am I the only one who thinks it's easier to read the official documentation? Oct 4, 2016 at 11:00
  • 3
    It's not first Google search result. If you code in C# your reference is MSDN (and GitHub.com/dotnet). Do you want to replicate everything on SO documentation? What's the added value? Oct 4, 2016 at 11:02
  • 1
    The problem (my opinion, of course) is that that point is the only one that deserves to stay in Documentation. Everything else is just a more verbose way to rewrite what I already can see in MSDN (honestly I do not need more than that...) I'd prefer to see a link to MSDN in Remarks section and in our doc just what MSDN does not cover. I'd be happy to browse Documentation to see 1) not obvious points - do you need to add a description of Object.ToString() method?!) 2) obscure features, 3) undocumented syntax/features 4) Good examples I can't find in MSDN/GitHub Oct 4, 2016 at 14:26
3

There is a lot of content in the Documentation feature that I think is worthwhile.

Keep in mind, this feature is in beta, getting biweekly updates, constant pushes, and has a lot of focus on its success - it is simply unwise to issue final statements on it in the current state as problems are being solved at a fast pace.

"Help us build a great library of canonical answers" - Joel Spolsky

We tried to build this canonical library of answers at Stack Overflow and while it did have some success, it struggled in many instances because the question and answer format is butchered when a user creates a canonical post. While some question and answer posts have become canonical by popularity or quality, often canonical posts get little attention.

What Stack Overflow desperately needed was a space for canonical posts. Reverse engineering a question and title to go with a canonical example of how to solve a wide spread problem proved difficult time and again, either by way of bad naming with regards to SEO once created, or because the solution was not localized to only one problem.

Documentation introduces a place where we can create canonical content with ease. While Stack Overflow's format did not provide a clean way for canonical content creation, Documentation does. The availability of space to create this content has already led to thousands of examples all with the available option to be curated by the community in order to maintain quality.

In my opinion, this feature was destined to succeed because it fills a niche that was otherwise unavailable.

2
  • 2
    So you're more or less saying that Documentation is a fresh start of Q&A, with only good content? Or am I reading too much into it?
    – user247702
    Oct 4, 2016 at 8:24
  • @Stijn - Documentation can be alongside Q&A, it isn't a replacement and it will more than likely not drive content away from the core Q&A. Documentation is not suited well for questions, Stack Overflow handles questions very well. It is creating canonical answers that we struggle with, and so providing a place for canonical examples is really a good niche that gets filled with the Documentation feature. I am sure you can find content which is not good in Documentation. If you do, improve it! You can vote for an improvement request or edit it yourself.
    – Travis J
    Oct 4, 2016 at 10:15

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