10 ms·

What I'm most worried about is the duplication between the canonical documentation of a project and the StackOverflow one. As the author of an open-source proj

What I'm most worried about is the duplication between the canonical documentation of a project and the StackOverflow one. As the author of an open-source project, I try my best to write a great documentation, and I would be a bit annoyed if people started to add examples to StackOverflow just to gain reputation there instead of contributing to the "official" one. Also, SO is ranked way higher than the smaller-projects' documentation on search engines, pointing developers there. This can be problematic, for example, if a big release comes out and the SO documentation is behind. The documentation for a lot of projects is really bad, I know, but I prefer a solution which doesn't disrupt the work of the mainteiners which writes good and extensive documentation.

allendoerfer 10y ago
I think they should link back to the official documentation wherever it makes sense. They could even automatically import official docs into their system if the license permits that and a standard tool is used.
- angry-hacker 10y ago
  They would still outrank your official docs. Just like wikipedia, they add nofollow to their links, meaning the links mean nothing in the eyes of Google. Instead of having some innovation when it comes to spammers, wikipedia and stack overflow punish the original content creators.
  - greglindahl 10y ago
    Search engines make their own opinions about nofollow links.
  - deleted 10y ago
    [deleted]
  - caf 10y ago
    They don't add nofollow on all links: http://meta.stackexchange.com/questions/111279/remove-nofollow-on-links-deemed-reputable http://meta.stackexchange.com/questions/111279/remove-nofoll... ("Starting today we will be removing nofollow on links within posts that hit a high enough threshold to be considered reputable. The details will remain somewhat vague at the moment to discourage gaming of this feature.")
JimDabell 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, 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.
amyjess 10y ago
Is this really going to be that different from things like the Arch wiki?
chx 10y ago
PHP, for example, has very good documentation with notes already (yes, more curation on notes would be even better) and this will cause a lot of duplication and confusion.
Tloewald 10y ago
Perhaps the solution is for StackOverflow to provide a "here's the official docs" bot that looks for questions that are answered by official docs and links to them (and perhaps provide a system for maintainers to give it hints).
dc2 10y ago
Agreed. I'm the author of Vorpal.js and already have community-maintained docs on Github's Wiki: https://github.com/dthree/vorpal/wiki https://github.com/dthree/vorpal/wiki Now I have to duplicate onto another community-maintained Wiki? This is only going to ask for problems. I don't really say "have to" lightly - StackOverflow is most definitely going to yield better search results in the long run.
tmptmp 10y ago
First of all a personal heartfelt "thank you" to you for contributing towards open-source project. It's because of people like you, who rise above the personal benefits to a significant extent and contribute to the open/free source movement, the people like me from the third-world can hope to learn anything significant without fearing about the costs involved. So I do appreciate your concern about SO grabbing all the credit due out there, but I politely wish to point out the need of better documentation of various open/free projects: The most important reason for me at least: The great RTFM famed man pages are the worst place to learn anything about how to use a particular tool for a newcomer because most of the times man pages lack good and varied examples. To quote Einstein, "Example isn't another way to teach, it is the only way to teach." - Albert Einstein [1] I have suffered endless time trying to learn things from man-pages. Spent time asking questions on forums until the expert people there saw the need to give some examples and offered help. I also thank them all. SO documentation can add much needed value for the newcomers here as experts can add examples and newcomers can find them at one place. This one is the greatest reason I support efforts like SO documentation project. Of course, I don't underplay the great work the open/free source contributors are doing. It may be the case that the great experts, may not find time to write down examples that a newcomer may need and the needs vary from one newcomer to another: One size doesn't fit all. The distributed crowd-sourcing model nature of SO can tackle this problem in a much better way, unless the truly open efforts like archive.org or gnu.org come ahead with hosting solutions like this. [1] http://www.alberteinsteinsite.com/quotes/einsteinquotes.html http://www.alberteinsteinsite.com/quotes/einsteinquotes.html
- pietroalbini 10y ago
  The documentation of a lot of projects is really bad, I know, and something is needed to improve it. I think though the efforts spent on duplicating documentation on SO is just wasted: why don't you contribute back to the canonical one? Usually maintainers are just happy to merge new documentation chapters or examples.
  - Flimm 10y ago
    Just editing something on Stack Overflow is much quicker than git cloning something, figuring out the documentation build that they have, editing, issuing a pull request, watching that pull request linger for ages, get a nit-picking comment, fix it, watch it linger for ages, and then finally merged, but not released, and then waiting for ages for the release. Obviously, sometimes the experience is better than that, and sometimes it's worse, but SO Q&A is much more consistent and immediate, and I imagine SO Docs will be as well.
aeorgnoieang 10y ago
The Stack Overflow Documentation content can be 'upstreamed' if it's worth doing so: - [Upstreaming content on Stack Overflow Documentation - Meta Stack Overflow](http://meta.stackoverflow.com/questions/328438/upstreaming-content-on-stack-overflow-documentation/328998#328998 http://meta.stackoverflow.com/questions/328438/upstreaming-c...) And the point of the whole feature is to document things without good canonical (or non-canonical) documentation: - [Creating a topic which already has good official documentation - Meta Stack Overflow](http://meta.stackoverflow.com/questions/328569/creating-a-topic-which-already-has-good-official-documentation http://meta.stackoverflow.com/questions/328569/creating-a-to...)
- detaro 10y ago
  Doesn't your first link explain why it generally can't be upstreamed, except if the project coincidentally also uses CC BY-SA 3.0, or a user makes a point explicitly granting a more compatible license?
avindroth 10y ago
I thought Google = Documentation for a long time. Now I need to resist the urge to just Google the question, I need to exert effort to find the documentation and make it handy.

allendoerfer 10y ago

I think they should link back to the official documentation wherever it makes sense. They could even automatically import official docs into their system if the license permits that and a standard tool is used.

angry-hacker 10y ago
They would still outrank your official docs. Just like wikipedia, they add nofollow to their links, meaning the links mean nothing in the eyes of Google. Instead of having some innovation when it comes to spammers, wikipedia and stack overflow punish the original content creators.
- greglindahl 10y ago
  Search engines make their own opinions about nofollow links.
- deleted 10y ago
  [deleted]
- caf 10y ago
  They don't add nofollow on all links: http://meta.stackexchange.com/questions/111279/remove-nofollow-on-links-deemed-reputable http://meta.stackexchange.com/questions/111279/remove-nofoll... ("Starting today we will be removing nofollow on links within posts that hit a high enough threshold to be considered reputable. The details will remain somewhat vague at the moment to discourage gaming of this feature.")

JimDabell 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, 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.

amyjess 10y ago

Is this really going to be that different from things like the Arch wiki?

chx 10y ago

PHP, for example, has very good documentation with notes already (yes, more curation on notes would be even better) and this will cause a lot of duplication and confusion.

Tloewald 10y ago

Perhaps the solution is for StackOverflow to provide a "here's the official docs" bot that looks for questions that are answered by official docs and links to them (and perhaps provide a system for maintainers to give it hints).

dc2 10y ago

Agreed. I'm the author of Vorpal.js and already have community-maintained docs on Github's Wiki: https://github.com/dthree/vorpal/wiki https://github.com/dthree/vorpal/wiki Now I have to duplicate onto another community-maintained Wiki? This is only going to ask for problems. I don't really say "have to" lightly - StackOverflow is most definitely going to yield better search results in the long run.

tmptmp 10y ago

First of all a personal heartfelt "thank you" to you for contributing towards open-source project. It's because of people like you, who rise above the personal benefits to a significant extent and contribute to the open/free source movement, the people like me from the third-world can hope to learn anything significant without fearing about the costs involved. So I do appreciate your concern about SO grabbing all the credit due out there, but I politely wish to point out the need of better documentation of various open/free projects: The most important reason for me at least: The great RTFM famed man pages are the worst place to learn anything about how to use a particular tool for a newcomer because most of the times man pages lack good and varied examples. To quote Einstein, "Example isn't another way to teach, it is the only way to teach." - Albert Einstein [1] I have suffered endless time trying to learn things from man-pages. Spent time asking questions on forums until the expert people there saw the need to give some examples and offered help. I also thank them all. SO documentation can add much needed value for the newcomers here as experts can add examples and newcomers can find them at one place. This one is the greatest reason I support efforts like SO documentation project. Of course, I don't underplay the great work the open/free source contributors are doing. It may be the case that the great experts, may not find time to write down examples that a newcomer may need and the needs vary from one newcomer to another: One size doesn't fit all. The distributed crowd-sourcing model nature of SO can tackle this problem in a much better way, unless the truly open efforts like archive.org or gnu.org come ahead with hosting solutions like this. [1] http://www.alberteinsteinsite.com/quotes/einsteinquotes.html http://www.alberteinsteinsite.com/quotes/einsteinquotes.html

pietroalbini 10y ago
The documentation of a lot of projects is really bad, I know, and something is needed to improve it. I think though the efforts spent on duplicating documentation on SO is just wasted: why don't you contribute back to the canonical one? Usually maintainers are just happy to merge new documentation chapters or examples.
- Flimm 10y ago
  Just editing something on Stack Overflow is much quicker than git cloning something, figuring out the documentation build that they have, editing, issuing a pull request, watching that pull request linger for ages, get a nit-picking comment, fix it, watch it linger for ages, and then finally merged, but not released, and then waiting for ages for the release. Obviously, sometimes the experience is better than that, and sometimes it's worse, but SO Q&A is much more consistent and immediate, and I imagine SO Docs will be as well.

aeorgnoieang 10y ago

The Stack Overflow Documentation content can be 'upstreamed' if it's worth doing so: - [Upstreaming content on Stack Overflow Documentation - Meta Stack Overflow](http://meta.stackoverflow.com/questions/328438/upstreaming-content-on-stack-overflow-documentation/328998#328998 http://meta.stackoverflow.com/questions/328438/upstreaming-c...) And the point of the whole feature is to document things without good canonical (or non-canonical) documentation: - [Creating a topic which already has good official documentation - Meta Stack Overflow](http://meta.stackoverflow.com/questions/328569/creating-a-topic-which-already-has-good-official-documentation http://meta.stackoverflow.com/questions/328569/creating-a-to...)

detaro 10y ago
Doesn't your first link explain why it generally can't be upstreamed, except if the project coincidentally also uses CC BY-SA 3.0, or a user makes a point explicitly granting a more compatible license?

avindroth 10y ago

I thought Google = Documentation for a long time. Now I need to resist the urge to just Google the question, I need to exert effort to find the documentation and make it handy.