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

41–50 of 136 posts

Re: Introducing Stack Overflow Documentation Beta

#41

Post by lucb1e »

kyriakos wrote: post #8

Great idea I especially appreciate the fact that its done by example. A couple of things that bothered me are: 1. The UI needs some refinement. I was looking to find a topic to post about and from my 10 minute browse I realised that if I was meant to find information in this documentation it's really hard to find what you are looking for. After you drill down to a tag it feels "unstructured". Readthedocs layout feels…

The UI needs some big improvements indeed. I toyed around with the site and although I could find my way around when just clicking through some topics, I am still confused as to what the structure of the site is (other than a list of topics, with a list of examples, not hierarchically structured or Q&A style or anything else that would make sense). I'm not sure I could find anything on here if I didn't get there via Google already.

Re: Introducing Stack Overflow Documentation Beta

#42

Post by troymc »

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 get made off this "documentation" (i.e. incoherent bag of examples) will not flow to the community or company behind the software in question. It's a parasite, leeching off the success of other projects which it neither created nor cares about.

How did they get corporate partners for their launch? That's easy. It looks to those companies like free labor.

Re: Introducing Stack Overflow Documentation Beta

#43

Post by orf »

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…

The same could be said about the general idea behind Stackoverflow, except it's wrong. Sure, it's "free labour for internet points" but so is posting a project to Github and wanting stars.

You're forgetting that it genuinely helps other people in your industry. Stackoverflow is an amazing resource for programmers, pretty much every question I type into google relating to a library or some software comes up with 3 or 4 stack overflow links that actually help me. If they can take the masses of questions which basically form ad-hoc documentation for tonnes of projects and put them in a cohesive place then how is this a bad thing? Because people don't get paid $0.01 per post or something?

Perhaps any advertising revenue from the docs site could go towards something good, would this be better?

Re: Introducing Stack Overflow Documentation Beta

#45

Post by lstamour »

acjohnson55 wrote: post #35
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…

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!

Re: Introducing Stack Overflow Documentation Beta

#46

Post by senex »

allendoerfer wrote: post #32

I think a big problem is user motivation. On Q&A sites you get the reward to directly help someone and have a conversation. This is missing for documentation. I wonder if their gamification is enough to motivate people or whether they have to find a deeper human desire that they build into this and satisfy.

Besides karma, I wonder if users will be motivated by career opportunities? Contributing to documentation could be a good signal to recruiters that are looking for experts in a particular technology.

Re: Introducing Stack Overflow Documentation Beta

#47

Post by akavel »

In the footnote of the post they wrote they considered naming it "SO Examples", but didn't. For me at least, using "SO Docs" to name the site is actually much more confusing. As a result, for the whole post I thought it is a dynamic manual, with per-function docs and examples. Only after browsing to the actual site I slowly realized it's not a manual: it's rather a "book" of examples. A list of HOWTOs, speaking in a language of yesteryear. As far as I see, it's impossible to build a MSDN in it. I couldn't add full documentation for one of Go packages here — borders cross vague, overlapping concepts, not clearly cut packages. To make it clear: I don't want to deny that it can be useful — suppose as examples for learning; but when looking for docs, I like being able to browse them systematically.

So, two possibilities: either something revolutionary I didn't fully grasp yet — or Examples, not Documentation.

For now, I much prefer the model of Go docs, MSDN, or PHP manual with user comments — if talking about docs.

Re: Introducing Stack Overflow Documentation Beta

#48

Post by hyperbovine »

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…

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

Except, who does that? Let's face it, most of us would rather be coding than writing docs. Consequently, a large number of high-profile projects (I won't name names) have surprisingly crap documentation. If SO can find a way break that spell, more power to them.

Re: Introducing Stack Overflow Documentation Beta

#49

Post by rohanpai »

This is super cool!

I am interning at Sourcegraph and we have heard devs want better usage examples too, so we automatically show all uses of any function

check out: -https://sourcegraph.com/github.com/golang/go/-/info/GoPackag... - https://sourcegraph.com/github.com/golang/go/-/info/GoPackag...

Post reply on HN