Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Introducing Stack Overflow Documentation Beta

blog.stackoverflow.com

Post reply on HN
Print view View original

91–100 of 136 posts

Re: Introducing Stack Overflow Documentation Beta

#91

Post by wool_gather »

pietroalbini wrote: post #67
drusepth wrote: post #62

Earlier quoted context omitted.

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

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.

Re: Introducing Stack Overflow Documentation Beta

#92

Post by evoltix »

jackcarter wrote: post #27

I hope they release a private enterprise version, like they have for StackOverflow[0]. I'd love to host this on-prem to document my company's codebase. Anyone know of a similar solution that's available now? [0] http://meta.stackexchange.com/questions/16054/is-the-stack-e...

I would definitely be interested in this as well.

Re: Introducing Stack Overflow Documentation Beta

#93

Post by Shog9 »

lstamour wrote: post #45
acjohnson55 wrote: post #35

Earlier quoted context omitted.

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 Comp…

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!

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.

Re: Introducing Stack Overflow Documentation Beta

#94

Post by [deleted] »

angry-hacker wrote: post #56
allendoerfer wrote: post #25

Earlier quoted context omitted.

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.

[deleted]

Re: Introducing Stack Overflow Documentation Beta

#95

Post by tmptmp »

pietroalbini wrote: post #24

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-projec…

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

Re: Introducing Stack Overflow Documentation Beta

#96

Post by caf »

angry-hacker wrote: post #56
allendoerfer wrote: post #25

Earlier quoted context omitted.

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.

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

Re: Introducing Stack Overflow Documentation Beta

#97

Post by visarga »

troymc wrote: post #42

This is awful, another trick site that fools people into doing work that they could be getting paid to do, all for the joy of getting some "karma." Well kids, karma ain't gonna pay the rent. If you want to get experience volunteering to write documentation for software, then find the existing official documentation and add to that (or start it, preferably in a repository close to the actual code). Any profits that ge…

> karma ain't gonna pay the rent

But other people's answers will help you solve your problem and earn your pay.

Re: Introducing Stack Overflow Documentation Beta

#98

Post by visarga »

blowski wrote: post #52
troymc wrote: post #42

This is awful, another trick site that fools people into doing work that they could be getting paid to do, all for the joy of getting some "karma." Well kids, karma ain't gonna pay the rent. If you want to get experience volunteering to write documentation for software, then find the existing official documentation and add to that (or start it, preferably in a repository close to the actual code). Any profits that ge…

> karma ain't gonna pay the rent My StackOverflow profile helped me get a new job with a good payrise. It's also helped me a better developer. I'm absolutely ok with them making a profit, and they're a hell of a lot more ethical and useful than what went before them.

Also, there's no better learning than when you teach the material to others. It's even being used as a didactic method (learning by teaching, peer learning).

Re: Introducing Stack Overflow Documentation Beta

#99

Post by d2ncal »

While this sounds like a good idea and will probably do well, it also centralizes more critical information and access to one for-profit company and product.

I really wish that we as a community would spend more effort towards better, decentralized systems.

Re: Introducing Stack Overflow Documentation Beta

#100

Post by hackaflocka »

archagon wrote: post #70
JimDabell wrote: post #26

Earlier quoted context omitted.

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 try…

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.
Post reply on HN