Introducing Stack Overflow Documentation Beta | Hacker News Reader

Introducing Stack Overflow Documentation Beta

blog.stackoverflow.com

481 pointssklivvz1971128 comments

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.

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.

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!

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 advice is that if you link a url you should include the meat of the link in your post to ward against link rot.

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

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.

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

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

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

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.

Money

internet points!

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.

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

Search engines make their own opinions about nofollow links.

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.

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.

(replying to self) Ok, I see now one area where it actually seems to make much sense and looks like it can work very nicely: for stuff like git, vim/emacs, bash, etc. Generalizing, I'd say: for apps/services which happen to have abysmal, irregular UX/API, which often accrued/emerged instead of being designed. A classical reference manual just doesn't work good enough for them, because the "natural" edges/borders in the API are too random and accidental. "SO Docs" as it is now can then organize the chaos, while making it easier to categorize & improve than a typical wiki.

http://stackoverflow.com/documentation/git/topics

http://stackoverflow.com/documentation/vim/topics

I agree with you, I was expecting a set of concurrent tutorials. I was hoping a coding version of http://www.mobafire.com/league-of-legends/champion/renekton-... where author trying to answer their best on "How to start coding?" and user reading and voting for their favorites tuto.

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 more user-friendly.

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.

Regards to no. 2 in your list, I was thinking something akin to MSDN, whereby one can change the version of the platform in question (Say MS SQL, .Net Framerwork)

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.

personally, google is how I always end up on stack overflow, so I'd imagine the same will be true for this product.

19 out of 20 times, true. However I totally get how SO is structured and contributing answers to people's question is something everyone gets. And if I want to find other questions (like for marking a duplicate, or researching a topic) I can use the search and tag system easily. Somehow the structure of this documentation area is not very clear to me.

#2 is actually implemented. Applicable versions are displayed on every page.

Regarding #2: I noticed that in Python there are content blocks that can be marked specific to a version.

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.

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?

That last point is an excellent idea, I could live with that, knowing the project maintainers get ad revenue each time I look up my own examples and examples by others. This is great.

I'm guessing that will never happen in any meaningful way, if only because that's not as profitable as keeping everything they get.

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

I think you're missing the point. Sure, getting "karma" is a fun aspect of SO, but I think what's beautiful about the site is the "give and take" aspect. Every programmer brings a different set of knowledge to the site, and every programmer also brings a different set of needs. And as long as people are not just using SO as tool for consumption, then the system is mutually beneficial for everyone. So, yes, while answering questions on the site does not pay the bills, what does pay the bills is my full time job as a developer. And I have been greatly helped in that job due to people donating their time, effort, and knowledge into SO. And that is why I don't see it as a waste of time to answer others' questions on the site or contribute to this documentation.

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

You're free to not use the site, I guess.

Right. Until your documentation gets co-opted by this external, third-party, for-profit company. The Q&A site is fantastic. But this new documentation thing is going to be a nightmare.

Creative Commons SA. They're not selling content, they're selling a platform for sharing content.

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

The worst part, imho, is moderators not getting a dime for all the work they do.

They're the ones that really run the Stack Exchange sites.

> karma ain't gonna pay the rent

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

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.

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.

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.

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.

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.

Not being able to comment at low karma is a cause of low quality answers from new users. They post answers that should be comments, and get down voted to hell. I think account age should also factor into a few of the low karma thresholds like being able to comment.

I remember that phase as well. It was frustrating, but it was worth it. Don't waste your time on the front page, just post questions and answers that are personally useful in your work, and eventually, you'll get the 5 upvotes needed to be able to comment everywhere.

If this gains traction I don't think we'll feel the benefits till a little later down the line.

I've contributed a little to the Swift tag but the real advantages come from technologies that don't already have good documentation.

I'm considering starting a tag for the enreco HTML -> PDF generator I use quite a lot as the official documentation isn't great.

> enreco HTML -> PDF generator

What is that? Googling it only brings up this comment thread.

Top result for me:

http://www.nrecosite.com/pdf_generator_net.aspx

My bad its Nreco

I'm actually very conflicted about Stack Overflow in general and of course the new documentation section as well.

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 http://webglfundamentals.org

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.

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?

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.

Links to what you wrote are welcome on SO and always have been, but link-only answers are not. Just summarise what you link to, and then recommend the link for the full answer.

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.

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.

Have you considered/tried adding back to the official documentation in cases like these?

Yes and yes. They just ignored my contributions.

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.

Like genius.com but for code documentation? :)

Edit:

Apparently they do it already: http://genius.com/web-annotator

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.

I understand this is (for now) for devs. I would love to see an equivalent (including private offering) for infra.

Getting people to document things on the infra side is deplorable in general and I would love to try anything that helps improve that.

"infra"? Quick google search did not illuminate me.

Infra as in infrastructure....

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.

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.

We have plans to eventually add Documentation to the data dump we already produce of the Q&A content (and hook it into the API, etc.)

If for some reason Documentation doesn't really take off or work and we end up scrapping the project, we'll produce a final dump of all content at that point.

The CC license used for stack overflow content is horrible. I have asked multiple lawyers what it means for cut-and-pasted code, and have yet to recieve a clear a definitive answer

- is it viral when compiled into a binary, or when used in scripts?

- how to attribute?

The license for code changed earlier this year: http://meta.stackexchange.com/questions/271080/the-mit-licen... to MIT. It's not retroactive, though.

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.

> a major destructive faction of nitpicks and deletionists on SO.

I've had my experience with them so I get where you're coming from, but you can't say StackOverflow isn't a great resource and perhaps in part because of them. I'm sure and am glad they will have their share in the documentation part as well.

Has Discourse failed?

Tell me about how it compares in usage to any of the solutions it set out to replace :-)

Or tell me about where people are using it to discuss every question that is not fit for SOs questions/answer format.

In my experience, those nitpicks and deletionists only agro at things they don’t understand, like any sufficiently complex question or topic.

I think PHP is going to be documented really well, I anticipate hundreds of wonderful examples how to get a substring or format a date-time from MySQL query result.

I doubt there will be much content outside of that.

I feel like this might be best used to document unexpected behavior or stupid things that maintainers may be too proud to acknowledge in their official manuals.

It should not be used to add redundancy. And it should not be used to accumulate cruft that doesn’t belong in any 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 - http://stackoverflow.com/documentation/java/88/streams#t=201...

Yep, examples with bugs.

This is cool.

It would be nice to have an API for this so that my IDE can pull these examples.

Awesome! I've actually been working on a java IDE that allows uploading examples together with the results to a website: http://jpad.io/example/1s/generating-random-int-array-within...

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.

So this makes Stack Overflow a library of example code curated by people who already frequent their website. Am I reading that right?

I think this will be separate from Stack Overflow Q&A, if that's what you were aiming at. SO Q&A will still target specific examples. But yes, the new SO Documentation project will be code examples and explanations curated by presumably many existing SO users.

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!

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

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.

Awesome! I've actually been working on a java IDE that allows uploading examples together with the results to a website: http://jpad.io/example/1s/generating-random-int-array-within....

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 https://news.ycombinator.com/item?id=12135897 and https://news.ycombinator.com/item?id=12136086 but I don't know if that's the right thing to have done?

linking to the more active discussion(!) and then flagging is the correct thing. If you do it before other comments have been added, this even flags the post as [dupe] automatically.

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

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?

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.

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!

"The docs" are remarkably inconsistent between projects. "The docs" for C# really don't need any help, "the docs" (by which I mean the AFAIK unofficial cppreference.com) for C++ are fine. But even major languages like Python don't have the greatest documentation, never mind the thousands of libraries out there that have wildly disperate levels of official "docs".

Exactly, and this should be fixed individually per project. If this is open-sourced project, you can contribute to the docs. If not — well, if not protected by some license, there will be side-projects with documentation, or you can make your own. But there should never be competition between actual documentation and some fucking for-profit organization, exactly for this reason: the documentation often is bad, and this can, and should be fixed.

Even then, often docs just cover the API and functions and fail to give an idea of "how can I use this?"

It would be nice if there is SO for business. Lots of companies have terrible internal documentation, Q/A tools.

Odoo Q&A is an open source clone of stackoverflow: https://www.odoo.com/page/community-builder

It has three mode: forum, Q&A (clone of SO), share links (like HN)

Very cool. Would be great if three functionality can be supported: transient chat, persistent Q/A and persistent documentation. The same for Stack Overflow. They may make a big profit if business start to use it.

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.

Anyone know if there are plans to roll this out to other stackexchanges? Would love to have this on askubuntu.com.

Odd.

Couldn't find blog.stackoverflow.com The Q&A site blog.stackoverflow.com doesn't seem to exist…yet.

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.

The blog was down for a bit and falling through to the generic Stack Exchange network handler, which is what you saw. It should be working now.

When I click the link, I get the blog post. When I go to blog.stackoverflow.com I get an overview of blogposts. What are you talking about?

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

Can we use existing SO answers to curate documentation?

looking forward for some standarized integration with github's wikis

Will be interesting to see what the moderation guidelines will be like, and how zealously they are "interpreted".

Will there be an example of a bad regular expression that could take down a website?

Reply on news.ycombinator.com