Hacker News Reader

Comment by pietroalbini | Hacker News Reader

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.

View on HN

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.

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.

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.

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.

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.

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.

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

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

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.

Search engines make their own opinions about nofollow links.

They don't add nofollow on all links:

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

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

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?

Agreed. I'm the author of Vorpal.js and already have community-maintained docs on Github's 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.

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.

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

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

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.

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

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.

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.

Reply on news.ycombinator.com