What I'm most worried about is the duplication between the canonical documentation of a project and the StackOverflow one.<p>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.<p>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.<p>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.
In the footnote of the post they wrote they considered naming it "SO <i>Examples</i>", but didn't. For me at least, using "SO <i>Docs</i>" 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 <i>a "book" of examples</i>. 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 <i>examples</i> for learning; but when looking for <i>docs</i>, I like being able to browse them systematically.<p>So, two possibilities: either something revolutionary I didn't fully grasp yet — or <i>Examples</i>, not <i>Documentation</i>.<p>For now, I much prefer the model of Go docs, MSDN, or PHP manual with user comments — if talking about <i>docs</i>.
Great idea I especially appreciate the fact that its done by example. A couple of things that bothered me are:<p>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 more user-friendly.<p>2. To future proof the documentation examples should come with a version number they apply to. For example there is PayPal and DropBox API examples which in a few months might no longer be valid.
This is awful, another trick site that fools people into doing <i>work</i> 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).<p>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.<p>How did they get corporate partners for their launch? That's easy. It looks to those companies like free labor.
Stack Overflow's point system is really annoying. I've been programming for around 10 years, but because I don't participate much I can't even comment on an answer.<p>A month or so ago I was stuck on a problem and thought I'd go through a tag for something I'm familiar with, and submit some answers to try and get enough points to be able to fully use the site.<p>One answer had a new programmer following a tutorial and using an old method signature. I commented that the tutorial he was following is out of date, and listed the correct method to use.<p>The person downvoted my answer, and then pasted (basically) the same code as the answer to his own question and accepted it. I know I just had bad luck in this case, but it's pretty frustrating.<p>Not allowing a user with low points to do some functions makes sense, but let them submit content and allow other users to determine if it's useful. I could have (and wanted to) comment on dozens of answers, which would of helped out a lot of people and saved them time/frustration.
If this gains traction I don't think we'll feel the benefits till a little later down the line.<p>I've contributed a little to the Swift tag but the real advantages come from technologies that don't already have good documentation.<p>I'm considering starting a tag for the enreco HTML -> PDF generator I use quite a lot as the official documentation isn't great.
I'm actually very conflicted about Stack Overflow in general and of course the new documentation section as well.<p>For whatever reason I answer many (most?) of the WebGL questions. At some point I felt I needed to make longer form answers with better working examples so I made <a href="http://webglfundamentals.org" rel="nofollow">http://webglfundamentals.org</a><p>But, now there's this huge conflict. I spent a couple hundred hours on making webfundamentals.org but when someone asks a question on stack overflow I'm not supposed to just link to whatever I wrote. I instead I'm supposed to effectively transfer all my content to SO. Something about that just feels wrong. SO is making money from the content I created which feels a little weird (yes I know I get other people's content back). Also, while I get that SO's gamification is part of what has made it so successful it's also feels like it turns many things into a competition. I try to tell myself don't worry about those points I'd be lying if I said they didn't affect me at all in various ways.<p>Taking all that and adding to documentation, as an example, when I contribute to MDN I feel like I'm doing something purely positive. But if/when I contribute to SO Docs I already know I'm not going to feel the same. One reason is because SO Docs will be making money from my work. The only thing I get in exchange is some "score" on my name I can maybe use to get a job. Maybe that's a fair trade since I don't get a score on MDN?<p>I'm not sure how to make my point. I love that I find answers on SO but something just doesn't feel right and I don't know how to express it.
This is awesome. I can't count the number of times I've found an Android function that has almost no documentation. I usually post a question and answer on SO if I work out how it works.<p>I only wish it were organised a bit more like normal documentation - i.e. into classes and methods. Might make it easier to find things.
I like the concept (reminds me of gobyexample.com) but this really isn't documentation. Instead of more code snippets I want high quality annotations (like snippets!) atop official documentation. If more people were driven to canonical docs but with a guiding hand I think we'd see more people actually understanding the code they write.
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.<p>Anyone know of a similar solution that's available now?<p>[0] <a href="http://meta.stackexchange.com/questions/16054/is-the-stack-exchange-engine-available-for-use" rel="nofollow">http://meta.stackexchange.com/questions/16054/is-the-stack-e...</a>
I understand this is (for now) for devs. I would love to see an equivalent (including private offering) for infra.<p>Getting people to document things on the infra side is deplorable in general and I would love to try anything that helps improve that.
Cool new project – I think it might become very helpful one day. Documentation for a lot of open source projects is pretty bad and having to figure out a new contributing workflow every time just to hop in and help a bit is quite problematic. Hopefully, the unified interface SO users are used to will give docs writing a big boost.<p>That said, I still hope they output some sort of GitHub repo of all the accepted changes to make it a bit less walled-gardeny. A CC license is nice and all, but having the content in a repo as well would put my mind at ease.
Really curious to see if this succeeds, fails like discourse or gets overrun by what I consider to be a major destructive faction of nitpicks and deletionists on SO.
I feel like this might be best used to document <i>unexpected</i> behavior or <i>stupid</i> things that maintainers may be too proud to acknowledge in their official manuals.<p>It should not be used to add redundancy. And it should not be used to accumulate cruft that doesn’t belong in <i>any</i> manual or list of examples. People have already gone for low-hanging fruit; for instance, do we really need examples of how to initialize a list?
If anyone is wondering how this looks and is impatient to read the blog post, here's an example Documentation page for Java Streams - <a href="http://stackoverflow.com/documentation/java/88/streams#t=201607211226138669707" rel="nofollow">http://stackoverflow.com/documentation/java/88/streams#t=201...</a>
Awesome! I've actually been working on a java IDE that allows uploading examples together with the results to a website:
<a href="http://jpad.io/example/1s/generating-random-int-array-within-range" rel="nofollow">http://jpad.io/example/1s/generating-random-int-array-within...</a><p>The idea is to build up libraries of examples in different areas, allow easy code sharing and to remove some of the cruft needed. It's good to see stackoverflow hit this "code examples" area better.
I really hope that all open source documentation quality will increased by adopting such kind of tools. The fact that SO is used an informal documentation was a strong signal that there were much improvement to be done. I am just sad because I wanted to work on project like that :'(. Great job SO !
This is super cool!<p>I am interning at Sourcegraph and we have heard devs want better usage examples too, so we automatically show all uses of any function<p>check out:
-<a href="https://sourcegraph.com/github.com/golang/go/-/info/GoPackage/net/http/-/NewRequest" rel="nofollow">https://sourcegraph.com/github.com/golang/go/-/info/GoPackag...</a>
- <a href="https://sourcegraph.com/github.com/golang/go/-/info/GoPackage/encoding/json/-/Encoder" rel="nofollow">https://sourcegraph.com/github.com/golang/go/-/info/GoPackag...</a>
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.<p>I really wish that we as a community would spend more effort towards better, decentralized systems.
Awesome! I've actually been working on a java IDE that allows uploading examples together with the results to a website: <a href="http://jpad.io/example/1s/generating-random-int-array-within.." rel="nofollow">http://jpad.io/example/1s/generating-random-int-array-within...</a>.<p>The idea is to build up libraries of examples in different areas, allow easy code sharing and to remove some of the cruft needed. It's good to see stackoverflow hit this "code examples" area better.
[META] This is popular, but is there a way to notify the mods of duplicates so that conversation doesn't get fragmented? I flagged <a href="https://news.ycombinator.com/item?id=12135897" rel="nofollow">https://news.ycombinator.com/item?id=12135897</a> and <a href="https://news.ycombinator.com/item?id=12136086" rel="nofollow">https://news.ycombinator.com/item?id=12136086</a> but I don't know if that's the right thing to have done?
Didn't see the word "test" in the article (except once talking about beta testing S.O.'s new product). And the word "test" isn't in these comments either, so...<p>Will updated examples be run through a program testing them in some way? If not a full run within a playground-style environment, then through a type checker?<p>And will the examples be tagged with version numbers? Some programming languages are notorious for changing syntax and/or semantics between minor versions.
I really don't want people to start using something like this instead of improving the official documentation. I hate the fact it probably cannot be helped.<p>To "do the same thing for docs that we did for Q&A"? Yeah, except there just was no sane platform for Q&A before. And for docs there is, you know… the docs!
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.
Odd.<p>Couldn't find blog.stackoverflow.com
The Q&A site blog.stackoverflow.com doesn't seem to exist…yet.<p>You can vote for it to be created through our democratic, community-driven process at area51.stackexchange.com, or see a complete directory of all our Q&A sites at stackexchange.com.
there's gotta be an integrated way to copy&paste examples (i.e. via autocompletion/snippet) from SO to our favorite code editor/IDE :D