It’s been 7 years and 10,000,000+ Questions since Stack Overflow was launched. The amount of good that has been done for the field - all the developers helped, all the person-hours saved, all the beginners who grew into professionals - is hard to overstate. I cannot express how proud I am of what we’ve built together (and not just because it let me see our arch-enemy vanish from my Google results); this community has realized the goal of "making the internet a better place" beyond what anyone could have predicted.
Lately we've been asking ourselves "what else could we do to improve developers' lives on the internet?". Jeff’s original announcement of Stack Overflow said this:
There's far too much great programming information trapped in forums, buried in online help, or hidden away in books that nobody buys any more. We'd like to unlock all that. Let's create something that makes it easy to participate, and put it online in a form that is trivially easy to find.
Stack Overflow has made all of that a lot better, but there's one area that is still hanging around: Documentation. Just like Q&A in 2008, Documentation in 2015 is something every developer needs regularly, and something that by most appearances stopped improving in 1996. We think, together, we can make it a lot better.
How would adding Documentation to Stack Overflow improve Documentation?
Documentation is often an afterthought, obviously done just to say that it exists, with little concern for its quality. We've all seen plenty of this in our time. We can bring a focus on quality, peer review, and "actually solves real problems for real developers"-ness to documentation that would be very welcome.
Often documentation is lacking in examples, or the examples are trivial and don't demonstrate typical use. Because Stack Overflow benefits from constant feedback from developers writing real-world code, we could greatly improve the quantity and quality of examples. Let's be honest: finding examples is already a common use-case for Stack Overflow; we might as well embrace it.
Much of the documentation out there is tied to release cycles, and thus infrequently updated and rarely "complete". The community-contributed and edited nature of Stack Overflow would be an immediate improvement.
A lot of documentation descends from Javadocs, and while it was better than nothing in '96, it's hard to call framesets with unshareable URLs "good" in 2015. We can focus on creating the best UX for creating and serving documentation on the modern web.
What would adding Documentation to Stack Overflow improve about Stack Overflow?
We've heard repeated requests for a place for broader artifacts to live. Less "a specific problem you are having right now," and more, "what is there for me to use." We think Documentation could provide a place for many of the useful artifacts that developers actively need, but we've been turning away over the years.
Many posts are improved by citing official documentation, but today, that means using offsite links that are sometimes hard to find and that may break. Having it on-site makes it easier to find and incorporate Documentation into posts.
There are Questions that come up repeatedly whose root cause is poor documentation. If you see a bunch of people struggle with Foo's Bar class, with Foo's documentation on Stack Overflow you could fix the Bar page and mitigate a source of repetitious (often exact duplicate) Questions.
A smaller, but just as real, benefit is that it opens up more opportunities for giving back. Oftentimes we'll hear from a developer who has benefited from a Stack Overflow Answer, but has trouble finding a Question they can help with that isn’t already answered. Documentation adds many more opportunities for paying it forward.
The Plan: We need YOUR help to build this
The first step is to share some rough ideas we've been kicking around for what the Documentation "part" of Stack Overflow might look like and how it might behave, and get your feedback. This is still in an early stage, but most of the successful ideas in Stack Overflow originated from the community, so we want you all in the loop as early as possible.
The second step will be a private beta, where we break everything and make the team cry test out the tools and workflows, but not on Stack Overflow proper. There's a sign-up form for this further down, so keep reading. Private beta will be shipping in the traditional six-to-eight weeks.
Or we're wrong. Maybe Documentation isn't as exciting to the community at large as it is to us, or we fail to iterate to a solution. Maybe we can't fill in that step.
But we think it's worth having a go at it. Interested? Give this post an upvote, and sign-up for the beta. Hate it? Downvote. Questions or comments? Well we've got more info below, but do post any and all feedback you have at the end - we want to hear your thoughts. After all, Stack Overflow is you.
How Documentation Will Work*
* we think
Tags that already have involved communities on Stack Overflow, such as .net or python, can have associated documentation created for them. Documentation is broken up into pages called Topics.
Topics always have Examples and Remarks; other sections are optional.
Examples are collapsible and deeplink-able. We're putting them at the top of the page because we believe they're the most important - the information you desire is likely within them. We're expecting Topics to have more Examples than Questions have Answers, since Topics will be broader than Questions.
Because Topics are envisioned as being much larger than the typical Question or Answer, trying to compose them in our current editor would be painful. So we're building a new one.
You can edit individual sections or Examples, you'll see a live preview, and your changes are automatically saved as drafts. We're still using Markdown and prettify for formatting and code styling, of course.
Anyone with sufficient privileges in a tag can create or edit Topics, and those without those privileges can suggest changes for review à la suggested edits. Those who think a Topic is needed, but cannot themselves write it, can instead request a Topic using the creatively named Request Topic button.
Requesters first search for an existing request to upvote, and if they find none, they can then enter a new request.
We're anticipating the typical good Request will be smaller than the typical good Question. A good Question has some explanation of the issue, a reproduction in code, and lists things that the asker has already tried. A good Request only has to explain the deficit in the Documentation. Because of this difference, we’re going with a much lighter UI in comparison to the Ask page.
For giving feedback on existing Topics, voting and flagging are available. These look very similar to existing flows, so they're not pictured.
All actionable items (request, pending changes, flags, votes, etc.) are aggregated into a dashboard view for people looking to help out.
Each "view more" and tab go to full lists like in the user profile.
All this stuff is very early and very much subject to change; especially now that we'll be getting your feedback.
FAQ
How will reputation work?
You'll get reputation for peer-reviewed contributions to Documentation. Peer review may take the form of citations, suggested edit reviews, explicit voting, or a combination of all three. Reputation you earn from Documentation will be added to the existing Q&A reputation; there won't be two separate numbers. Obviously, we're still working out lots of the details.
We intend for participation in the Documentation parts of Stack Overflow to be about as rewarding, in terms of reputation, as asking and answering is in the Q&A parts.
What can be documented?
We're thinking "anything you use through code" as a really rough guideline, but we'll ultimately decide together as a community, just like with what’s on-topic for Q&A.
For the betas, we're planning to restrict ourselves to established and widely used projects. We're trying to test out the bigger stuff first, to make sure all the tools and processes can cope. If all goes well, eventually just about anything that sees some Q&A activity will be fair game to document.
What should be documented?
- Anything where we can actually make it better. If a project already has awesome documentation that's easy to search and cite, then there's no need to duplicate it on Stack Overflow. We're interested in fixing what's broken with documentation, not just moving them onto Stack Overflow.
What's the line between a Question and a request for a Topic?
Topics are broader in scope than Questions. In fact, we're expecting that if you "asked" most requests, they’d be closed as Too Broad.
Topics should also have multiple Examples, so a request that can be served by a Topic with a single Example (ie. one block of code) is probably too narrow.
Is importing existing documentation encouraged?
- No. We're hoping we can improve documentation, not just move it under the stackoverflow.com domain.
What license will documentation be under?
- The same license (Creative Commons Attribution Share Alike) and ToS that covers existing content. Documentation will also appear in our regular data dumps once the private beta concludes.
We’ll need to know three things:
- Your email
- Your Stack Overflow profile URL
- A list of 2-5 tags you’d be interested in helping document
Please pick tags from the first two pages of popular tags that have an especially active community. Things like c#, r, or ios so we can test our system out against the real things that lots of developers are using in the private beta.
docs.stackoverflow.com
portal? With a Google-like search field, a tag selector, and specific information around docs? With users signing up separately, as they would to a different SE site?