Hacker News Reader

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.

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!

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.

So the answer is to not use links at all?

Sometimes it's better to pass by value, sometimes it's better to pass by reference.

Put the content AND the link, instead of just the link. This way, if the link changes the info will stay in SO.

Wouldn't that be a copyright violation?

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.

But that violates DRY principle tho

The Y in DRY is "yourself". Therefore, if you are a strict adherent to DRY, feel secure in knowing it's perfectly allowed to repeat someone else.

I guess jokes don't work

Zero percent chance of valid source is worse than some percent chance.

Fortunately, as I said earlier, anyone can edit. We should definitely make links, they greatly increase the utility of a post. If they rot, it just takes one person to make the fix.

I think the advice is that if you link a url you should include the meat of the link in your post to ward against link rot.

Donno who told you that, but have it straight from the project lead:

> it's fine to link to external sources, but the same basic "content should stand on it's own"-guidelines apply (so no link-only examples and the like)

- http://chat.stackoverflow.com/transcript/117558?m=31845619#3...

Which is pretty standard advice on Stack Overflow; we spend an awful lot of time cleaning up broken links that were probably pretty useful at one time, but...

Disclaimer: I work for Stack Overflow and also really hate broken links.

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.

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.

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.

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

Money

Never underestimate the human desire to aggregate and have "everything in one place".

internet points!

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.

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

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.

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.

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

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

Until you need to innovate. It sounds like a skill for worker bees.