5 ms·

There's one question I saw on Stack Overflow a while back that irritated me. If you copied and pasted the literal question directly into Google, the top hit wa

There's one question I saw on Stack Overflow a while back that irritated me. If you copied and pasted the literal question directly into Google, the top hit was directly to the canonical documentation, where you could just scroll down to the clearly marked heading, and copy and paste the sample code and have it work straight away. When I pointed this out, I was berated for not understanding that Stack Overflow is trying to become the canonical source. Sure enough, a few weeks later, the top hit on Google no longer pointed at the official documentation. It pointed at that same Stack Overflow question, with a half-assed answer that only gave a fraction of the information the real documentation did. I appreciate Stack Overflow for its strengths, but it's harmful too. Being able to go directly to the canonical source of information for a product and do your job without anybody spoon-feeding everything to you is a vital developer skill, and I'm seeing more and more people who won't bother to lift a finger unless somebody does half their work for them. This project seems like it will push the developer community much further down this path.

TylerH 10y ago
SO Q&A is definitely not trying to be the canonical source, and neither is Documentation. Whoever told you that was Wrong(TM).
- Piskvorrr 10y ago
  Like Wikipedia, it strives to be a great first-order approximation (from where you'd browse over to the canonical sources). Unlike Wikipedia, it doesn't make this too clear, and I have met people claiming that SO intends to obsolete primary sources - a tragic misunderstanding.
acjohnson55 10y ago
To be fair, that best answer is totally editable by any user to be more informative and/or link to the canonical source of information. There are few projects whose docs have such low contribution friction, for better or worse. And unlike project-specific documentation, it comes in one basic format and set of norms. I also don't think there's a problem of spoonfeeding information to developers. If a developer at Company X tries to solve all their problems via StackOverflow questions, waiting for someone to come save them, I'd have to assume that this would manifest as them being blocked all the time. At that point, it's up to their lead to teach them and hold them accountable for exercising other ways of resolving their problems, including RTFM.
- lstamour 10y ago
  I was just idling in the Documentation chat channel and based on what I was seeing there, it appears links to sources are discouraged on StackOverflow documentation. Presumably, they're aiming to eventually host new content that's better than what's already out there. I think it's a bit silly -- at least make a Sources section where folks can click to view links to existing docs!
  - recursive 10y ago
    Everyone knows that cool urls don't change, but the problem with links is that not all urls are cool urls. Links rot over time.
    - theli0nheart 10y ago
      So the answer is to not use links at all?
      - voxic11 10y ago
        Sometimes it's better to pass by value, sometimes it's better to pass by reference.
      - sanbor 10y ago
        Put the content AND the link, instead of just the link. This way, if the link changes the info will stay in SO.
        true_religion 10y ago
        Wouldn't that be a copyright violation?
        slavik81 10y ago
        Like in any other writing, a short quote is fine. If it's long, then you may have to summarize the content in your own words.
d0mine 10y ago
Did you leave a comment (under the corresponding StackOverflow question/answer) with a link to a correct (from your point of view) example? The official docs are the reference (and at best some common questions are answered). Stack Overflow is a Q&A site. It doesn't replace the docs; it complements them. The new "Documentation" section on stackoverflow is just categorized code examples created and ranked by the community. It doesn't replace the docs too. Though It is not clear how the Documentation feature will evolve and whether it will be as useful as the Q&A part.
drusepth 10y ago
Honestly, this seems more like a problem with search algorithms than Stack Overflow. If the canonical documentation is more helpful to more people, it should rank higher. If Stack Overflow Documentation is more helpful, _it_ should rank higher. It doesn't hurt to try to create a resource that might end up being more useful to more people. But until it really is, it needs to be ranked as so.
- pietroalbini 10y ago
  My point is, why would you duplicate documentation both on the canonical source and in Stack Overflow? For example, Flask [1] has a great and complete documentation, but still someone is starting to duplicate it on SO Docs. Why are we wasting time duplicating things instead of improving what's already there? [1] http://flask.pocoo.org http://flask.pocoo.org
  - bjg 10y ago
    Money
  - pcsanwald 10y ago
    Never underestimate the human desire to aggregate and have "everything in one place".
  - bvirkler 10y ago
    internet points!
  - wool_gather 10y ago
    It's been explicitly said by the SO staff that Documentation should _not_ be used to replace or duplicate existing good docs. The official goal is filling in holes, not taking over. It's only the first day, and there are a lot of people scribbling, but there are also a lot of eyeballs on it (user review of edits is how Docs works). Hopefully over the long run we can keep a lid on this kind of information smearing.
archagon 10y ago
I think the problem is that incomprehensible documentation is pretty much the norm. When RTFM-ing leads to immense frustration nine times out of ten, why would anyone do it just for that one time when it actually works? If I need help with a tool or framework, what I'm usually looking for is a code sample explained quickly in human terms: a service that SO specializes in.
- hackaflocka 10y ago
  This post hits the nail on the head. The original manual often sucks (e.g., examples in the PHP manual are often incomprehensible to me). SO often does a better job. Competition is good. If SO becomes the favored destination, so be it.
namuol 10y ago
> I'm seeing more and more people who won't bother to lift a finger unless somebody does half their work for them. Most work has already been done. Sounds like a good quality to have.
- fapjacks 10y ago
  Until you need to innovate. It sounds like a skill for worker bees.
tedmiston 10y ago
> There's one question I saw on Stack Overflow a while back that irritated me. If you copied and pasted the literal question directly into Google, the top hit was directly to the canonical documentation ... I see this on SO a lot. Some developers just have different experience levels, and are better/worse at searching through docs.

TylerH 10y ago

SO Q&A is definitely not trying to be the canonical source, and neither is Documentation. Whoever told you that was Wrong(TM).

Piskvorrr 10y ago
Like Wikipedia, it strives to be a great first-order approximation (from where you'd browse over to the canonical sources). Unlike Wikipedia, it doesn't make this too clear, and I have met people claiming that SO intends to obsolete primary sources - a tragic misunderstanding.

acjohnson55 10y ago

To be fair, that best answer is totally editable by any user to be more informative and/or link to the canonical source of information. There are few projects whose docs have such low contribution friction, for better or worse. And unlike project-specific documentation, it comes in one basic format and set of norms. I also don't think there's a problem of spoonfeeding information to developers. If a developer at Company X tries to solve all their problems via StackOverflow questions, waiting for someone to come save them, I'd have to assume that this would manifest as them being blocked all the time. At that point, it's up to their lead to teach them and hold them accountable for exercising other ways of resolving their problems, including RTFM.

lstamour 10y ago
I was just idling in the Documentation chat channel and based on what I was seeing there, it appears links to sources are discouraged on StackOverflow documentation. Presumably, they're aiming to eventually host new content that's better than what's already out there. I think it's a bit silly -- at least make a Sources section where folks can click to view links to existing docs!
- recursive 10y ago
  Everyone knows that cool urls don't change, but the problem with links is that not all urls are cool urls. Links rot over time.
  - theli0nheart 10y ago
    So the answer is to not use links at all?
    - voxic11 10y ago
      Sometimes it's better to pass by value, sometimes it's better to pass by reference.
    - sanbor 10y ago
      Put the content AND the link, instead of just the link. This way, if the link changes the info will stay in SO.
      - true_religion 10y ago
        Wouldn't that be a copyright violation?
        slavik81 10y ago
        Like in any other writing, a short quote is fine. If it's long, then you may have to summarize the content in your own words.

d0mine 10y ago

Did you leave a comment (under the corresponding StackOverflow question/answer) with a link to a correct (from your point of view) example? The official docs are the reference (and at best some common questions are answered). Stack Overflow is a Q&A site. It doesn't replace the docs; it complements them. The new "Documentation" section on stackoverflow is just categorized code examples created and ranked by the community. It doesn't replace the docs too. Though It is not clear how the Documentation feature will evolve and whether it will be as useful as the Q&A part.

drusepth 10y ago

Honestly, this seems more like a problem with search algorithms than Stack Overflow. If the canonical documentation is more helpful to more people, it should rank higher. If Stack Overflow Documentation is more helpful, _it_ should rank higher. It doesn't hurt to try to create a resource that might end up being more useful to more people. But until it really is, it needs to be ranked as so.

pietroalbini 10y ago
My point is, why would you duplicate documentation both on the canonical source and in Stack Overflow? For example, Flask [1] has a great and complete documentation, but still someone is starting to duplicate it on SO Docs. Why are we wasting time duplicating things instead of improving what's already there? [1] http://flask.pocoo.org http://flask.pocoo.org
- bjg 10y ago
  Money
- pcsanwald 10y ago
  Never underestimate the human desire to aggregate and have "everything in one place".
- bvirkler 10y ago
  internet points!
- wool_gather 10y ago
  It's been explicitly said by the SO staff that Documentation should _not_ be used to replace or duplicate existing good docs. The official goal is filling in holes, not taking over. It's only the first day, and there are a lot of people scribbling, but there are also a lot of eyeballs on it (user review of edits is how Docs works). Hopefully over the long run we can keep a lid on this kind of information smearing.

archagon 10y ago

I think the problem is that incomprehensible documentation is pretty much the norm. When RTFM-ing leads to immense frustration nine times out of ten, why would anyone do it just for that one time when it actually works? If I need help with a tool or framework, what I'm usually looking for is a code sample explained quickly in human terms: a service that SO specializes in.

hackaflocka 10y ago
This post hits the nail on the head. The original manual often sucks (e.g., examples in the PHP manual are often incomprehensible to me). SO often does a better job. Competition is good. If SO becomes the favored destination, so be it.

namuol 10y ago

> I'm seeing more and more people who won't bother to lift a finger unless somebody does half their work for them. Most work has already been done. Sounds like a good quality to have.

fapjacks 10y ago
Until you need to innovate. It sounds like a skill for worker bees.

tedmiston 10y ago

> There's one question I saw on Stack Overflow a while back that irritated me. If you copied and pasted the literal question directly into Google, the top hit was directly to the canonical documentation ... I see this on SO a lot. Some developers just have different experience levels, and are better/worse at searching through docs.