Some thoughts:

The documentation sample enumerates a class's constructor overloads and their parameters. I don't think this is a good sort of thing to include, and could even be outright harmful. I think we should avoid anything that resembles standard documentation of functions, their parameters, their return types, their error conditions etc, for several reasons:

• It will always be a less authoritative source than the official documentation. For example, imagine if the official documentation says that a method may throw a IllegalStateException in some obscure multuthreaded scenario but the Stack Overflow "documentation" leaves that exception out, and a developer thus designs their code without on the assumption that the method cannot fail, just who is liable when the exception occurs? Is it the developer, for trusting the popular Stack Overflow documentation? Is it the Stack Overflow contributor who documented things ever-so-nearly-completely but not fully-actually-completely? Is it the API developer, who, realizing that everyone now depends on the exception not occurring, is faced with the prospect of reimplementing the API to cater to the common usage, whatever the cost? With third-party documentation, blame is diffused and no-one in particular is responsible.

  On the other hand, official documentation is more than just an explanation of what things mean. It's a promise about how things work, a contract that the API writer makes with the API users to support a particular usage. No-one other than the API writer can make such a promise, because no-one else is responsible for writing the code that honors it. If they don't honor it at least you have someone to blame.

• It will always be less complete than official documentation (which, even if it's auto-generated, will at least include mention of every API member, whereas rep-driven documentation writers could leave obscure things out).

• I fear it will struggle to cope with changes between API versions.

• Overall, I can't imagine that it will be better than the "Gets the row enumerator" style documentation it seeks to replace.

If there is value in user-contributed documentation, it lies in creating the examples and tutorials of real-world usage.

This could be good. I'm tentatively in favor of the experiment. However, I'm worried by the overlap with the Q&A format. I envisage a lot of argument about what belongs as a documentation topic and what should be presented as Q&A and/or tag wiki. New users will be especially confused. I've read this page several times and I'm still confused. If the line can't be drawn clearly then it's going to cause so much fuss that we should not bother with the feature, and should stick to Q&A and tag wikis.

Addendum: I'm not looking forward to the inevitable gold rush when the feature goes live. It is already the case that Stack Overflow rep is based much more on post visibility than on post effort, and a big part of visibility is being first to snipe in with an answer or question. (We all know this, and we all do it, even though we like to think our own rep scores are based on nothing but pure cleverness.) I expect that opening up an entire new section of the site will cause a new race to snag the common issues and popular topics. Speed and quantity will be rewarded with rep more than quality. It's going to be a race to grab land to plant the seeds of future rep growth, and it's not going to be friendly.

Some thoughts:

The documentation sample enumerates a class's constructor overloads and their parameters. I don't think this is a good sort of thing to include, and could even be outright harmful. I think we should avoid anything that resembles standard documentation of functions, their parameters, their return types, their error conditions etc, for several reasons:

• It will always be a less authoritative source than the official documentation. For example, imagine if the official documentation says that a method may throw a IllegalStateException in some obscure multithreaded scenario but the Stack Overflow "documentation" leaves that exception out, and a developer thus designs their code on the assumption that the method cannot fail, just who is liable when the exception occurs? Is it the developer, for trusting the popular Stack Overflow documentation? Is it the Stack Overflow contributor who documented things ever-so-nearly-completely but not fully-actually-completely? Is it the API developer, who, realizing that everyone now depends on the exception not occurring, is faced with the prospect of reimplementing the API to cater to the common usage, whatever the cost? With third-party documentation, blame is diffused and no-one in particular is responsible.

  On the other hand, official documentation is more than just an explanation of what things mean. It's a promise about how things work, a contract that the API writer makes with the API users to support a particular usage. No-one other than the API writer can make such a promise, because no-one else is responsible for writing the code that honors it. If they don't honor it at least you have someone to blame.

• It will always be less complete than official documentation (which, even if it's auto-generated, will at least include mention of every API member, whereas rep-driven documentation writers could leave obscure things out).

• I fear it will struggle to cope with changes between API versions.

• Overall, I can't imagine that it will be better than the "Gets the row enumerator" style documentation it seeks to replace, although it will be better in some places and worse in others.

If there is value in user-contributed documentation, it lies in creating the examples and tutorials of real-world usage.

This could be good. I'm tentatively in favor of the experiment. However, I'm worried by the overlap with the Q&A format. I envisage a lot of argument about what belongs as a documentation topic and what should be presented as Q&A and/or tag wiki. New users will be especially confused. I've read this page several times and I'm still confused. If the line can't be drawn clearly then it's going to cause so much fuss that we should not bother with the feature, and should stick to Q&A and tag wikis.

Addendum: I'm not looking forward to the inevitable gold rush when the feature goes live. It is already the case that Stack Overflow rep is based much more on post visibility than on post effort, and a big part of visibility is being first to snipe in with an answer or question. (We all know this, and we all do it, even though we like to think our own rep scores are based on nothing but pure cleverness.) I expect that opening up an entire new section of the site will cause a new race to snag the common issues and popular topics. Speed and quantity will be rewarded with rep more than quality. It's going to be a race to grab land to plant the seeds of future rep growth, more than an altruistic collaboration to build ideal documentation.