2914
votes

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?

  1. 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. Bad documentation is bad 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.

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

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

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

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

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

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

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

Then a miracle occurs

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.

Failure is always an option

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 or , can have associated documentation created for them. Documentation is broken up into pages called Topics.

Topic page

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.

The new editor

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.

Searching for an existing request

Requesters first search for an existing request to upvote, and if they find none, they can then enter a new request.

Submiting a Topic 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.

Dashboard mockup

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

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

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

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

  5. Is importing existing documentation encouraged?

    • No. We're hoping we can improve documentation, not just move it under the stackoverflow.com domain.
  6. What license will documentation be under?

## Register For The Beta

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 , , or so we can test our system out against the real things that lots of developers are using in the private beta.

Register and help Make Docs Suck Less

198
  • 155
    4 minutes - 15 upvotes? Who can read such a long post so fast? Commented Aug 31, 2015 at 15:34
  • 253
    "We’re interested in fixing what’s broken with documentation, not just moving them onto Stack Overflow." - Assuming this works how you want, if a project improves documentation to the point where it's not needed on SO any longer, will there be a process to encourage users to go back to the project itself instead of continuing here?
    – Andy Mod
    Commented Aug 31, 2015 at 15:39
  • 164
    I wonder how, in the case of something like .NET, this would be better than MSDN. Maintenance would be another concern generally. Things change. Commented Aug 31, 2015 at 15:41
  • 32
    @Andy in the same way that a community could stop posting to Stack Overflow Q&A, yes. Ultimately the contributors control the content, if they're convinced to tear everything down and point folks at the official docs then that's fine. If it turns out we need to build tools for such a process, we will. Commented Aug 31, 2015 at 15:43
  • 36
    @Plutonix read #3 on the FAQ again. They don't want to replace existing documentation if the existing docs are good enough. However, I'm wondering how we could somehow supplement existing documentation with better examples, because some of the examples and information on MSDN (and plenty of other OSS documentation) sucks.
    – Dave Zych
    Commented Aug 31, 2015 at 15:44
  • 34
    Along the same lines as the concern indicated by @Andy, would there be some process to discourage people from creating 'usurping' documentation sets that have the effect of making other documentation worse (or, more likely, die on the vine)? The first thing that came to mind is asp.net-5 - docs.asp.net is really incomplete, but it's collaborative and could be made quite good with enough contributions. What happens when all those potential contributors do it here instead? (comment a little out-of-sync with your response to Andy..) Commented Aug 31, 2015 at 15:44
  • 22
    @Plutonix we have some ideas about handling version releases (tl;dr version tables and inference), as well as obsolescence (tl;dr flagging and markdown extensions). This post was pretty long already though, so I cut it. We'll have some super detailed stuff when the beta starts, you're correct that this stuff is tricky. Commented Aug 31, 2015 at 15:46
  • 27
    WRT point #5, if the tag wikis are the recipients of plagiarized content now, I can't wait to see how the documentation pages end up. I definitely like the idea though.
    – j08691
    Commented Aug 31, 2015 at 15:54
  • 19
    Love the idea, but worried about visibility if this is confined to tag wikis or a similar corner on SO with relatively low "through traffic". Would this perhaps warrant a separate 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?
    – Pekka
    Commented Aug 31, 2015 at 15:56
  • 180
    Maybe we could take this opportunity to improve licensing: explicitly dual-license code samples in docs as MIT, not just Creative Commons, so they're clearly safe to reuse.
    – Jeremy Banks Mod
    Commented Aug 31, 2015 at 15:57
  • 82
    How would the project deal with the danger of documentational ghost towns? Say a bunch of people wants to create SO docs for something that already has decent documentation of its own. They may want to mine rep, or genuinely feel they can contribute something great but aren't allowed to in the project's own docs. Because the larger community isn't with them, the effort withers away quickly and leaves a half-finished pile of partially useful information. How to prevent that?
    – Pekka
    Commented Aug 31, 2015 at 16:15
  • 65
    One of the most difficult things to enforce to maintain utility will be versioning. Here I refer to the version of the thing being documented. There is already much in the questions section that doesn't have good versioning and most of the time it works. How to inject discipline into the documentation consistently? Commented Aug 31, 2015 at 16:27
  • 45
    First, I'd like to recommend that the design lend itself to printing. I still print out documentation and write all over it, so make sure there's some thought put into the printer style sheets. Second, you said "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 ". I think this is wrong, and parameters and syntax should be required while remarks should be optional. And since syntax will usually be shorter than the examples, it should be 1st.
    – j08691
    Commented Aug 31, 2015 at 16:35
  • 23
    I like the idea, but it shouldn't be part of Stack Overflow. It should be a seperate thing.
    – Jeroen
    Commented Aug 31, 2015 at 19:02
  • 52
    Will it replace W3Schools just like SO replaced Experts Exchange?
    – Uwe Keim
    Commented Sep 4, 2015 at 19:16

94 Answers 94

1 2 3
4
1
vote

I added this to my Y Combinator application's extra ideas part. (It wasn't accepted.) I really thought this topic through, how it should be, how it's going to make the world a really better place, because it will directly affect the rate at which technology is developed.

If you had any other ideas you considered applying with, please list them. One may be something we've been waiting for. Often when we fund people it's to do something they list here and not in the main application.

Wiki - examples - overflow: People don’t learn from definitions, people learn from examples. It is Wikipedia model for examples that can teach any topic.

I would like to contribute more than the regular "beta user".

1
vote

If a company doesn't pay attention to the quality of its commercial product, then such product should die.

Writing some additional documentation that the company does not pay for is going to encourage such practices to repeat in the future.

3
  • 1
    Exactly what I fear too. A well-documented library (or product, api,...) generally means it's well written and well thought-out. I only trust libraries written by people who know how to write and take the effort to do so. The quality of a library can often be judged by the quality of the documentation. Libraries or products without good documentation should, and likely will, just die. Instead, imo, effort should be put in making it easier to write nice documentation and allow contributions - on the product website itself. Like what readthedocs.org is doing. Eg: docs.asp.net . Commented Sep 11, 2015 at 10:39
  • 1
    if a company is just one enthusiast which make some cool thing which no one made before and he in need in help from community to write some docs, i think, he and his project should live and prosper On this moment i don't know real opportunity to attract large community for this goal. I think your answer is not very polite and correct at all.
    – Mikl
    Commented Sep 11, 2015 at 13:31
  • @Mikl if company(single dev) wants help on documenting then library + documentation is effort of group of people not original dev. If that is so then such dev should open source the library and no longer pretend it is his own work. Commented Sep 11, 2015 at 20:12
0
votes

enter image description here

3
  • 3
    I was reading the answers and then this... I started to laugh, thx GEOCHET to make me laugh... it doesn't happen often these days... Commented Aug 31, 2015 at 20:05
  • 1
    Hooray for a sense of humor bob, something too many people seem to lack.
    – GEOCHET
    Commented Aug 31, 2015 at 22:25
  • A day I read somewhere (I don't remember the source) « Humor it's a serious thing, people without humor aren't serious » Commented Sep 1, 2015 at 18:22
-9
votes

The project has power, but the idea itself should change.

Documentation should not contain working examples, but fragments of code only if needed to better illustrate the topic during explanation.

Stack Overflow is a Q&A site: examples should be the goal of that part of it! My idea of Documentation is much more like the Javadoc-style: each unit has its own brief description, and that's all.

I like that user interface. Don't forget to permalink everything!

3
  • What about api docs ? Ever looked at swagger.io ?
    – lxx
    Commented Sep 3, 2015 at 1:03
  • 2
    @lxx Those are the Javadocs.
    – user3453226
    Commented Sep 4, 2015 at 12:11
  • javadocs don't cut it anymore especially for web api's and services
    – lxx
    Commented Sep 5, 2015 at 23:20
1 2 3
4

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .