News

Stack Overflow Tackles Code Documentation, Not Just Q&A

• By David Ramel
• July 21, 2016

Stack Overflow, the immensely popular coding Q&A forum that has become the go-to resource for developers seeking help with specific problems, is now supplying more general documentation with today's beta launch of an ambitious new site.

After a private beta, Stack Overflow Documentation is now available in a public beta, characterized by the company as "our biggest expansion to Stack Overflow since it first launched" back in 2008.

The focus of the new site is providing code examples for various topics, documenting concepts ranging from the ubiquitous Hello World program in Java to the details of using overloaded literals in Haskell. In fact, the site was almost called "Stack Overflow Examples," company exec Kevin Montrose said in a blog post today.

"We learned that our Q&A works best when you've got a real problem, specific to the code in front of you," Montrose said. "By coming to terms with that, and tweaking Stack Overflow accordingly, we've become much better at Q&A but have left some programming knowledge out in the cold.

"Documentation gives a home to a lot of this good content that has been turned away, or very hard to 'get right' in the Q&A format. Namely, the canonical, general reference, instructional content."

The lack of such content was cited as a primary developer pain point in Stack Overflow's own research, the site said in a news release today.

"According to the 2016 Annual Developer Survey, poor documentation ranked as one of the biggest challenges facing developers in their day-to-day jobs," the site said. "Stack Overflow Documentation will complement and improve existing technical documentation by turning instruction manuals into living resources that developers can update in real time with new use cases, implementations and integrations."

"Just like we did with Q&A, the goal of Documentation is to solve real-world developer problems," said exec Jay Hanlon in the statement. "By harnessing the sum total of good programming knowledge in the world, we can create something more useful than any individual or team could on their own."

If the site follows the track of its parent, Stack Overflow (itself part of Stack Exchange Inc. umbrella organization), it will soon become an invaluable resource for developers around the world. Stack Overflow -- "the largest online community for programmers to learn, share their knowledge and advance their careers" -- attracts some 40 million monthly visitors, the site says.

Using a merit-based voting system to surface the best content as judged by all those users, it has become so authoritative that companies actually refer to it as the best source of technical help. For example, documentation for the popular React Native technology developed by Facebook says:

If you're wondering how to solve a specific technical problem in React Native, the best place to ask is on Stack Overflow. You can check existing questions tagged with react-native, ask your own, or just Google it and click on the Stack Overflow answer that will inevitably come up.

The company is now hoping that gravitas transfers to the new documentation site.

"Together, we believe we can do the same thing for technical documentation that we did for Q&A," reads the Montrose blog post.

"Examples, examples, examples -- show beats tell," Montrose said. "In Stack Overflow Documentation, examples are the star of the show. Anyone can add one, so good topics will eventually have several useful examples. And much like answers on Stack Overflow, the most helpful ones will usually be voted up to be right on top."

To help the fledgling site get started, developers from companies such as Microsoft, Dropbox, PayPal, Xamarin, Twilio, PubNub, Twitch and Meteor will be participating along with the general developer community.

"They'll be watching to see what kind of great examples and documentation are created to inform their own work and help answer or clarify anything that needs it," Montrose said. "They're Stack Overflow users like everyone else, we're all working together (to help developers everywhere), so you could see your change reviewed by a Microsoft-y or find a request from a Dropbox-er."

Montrose, who said the Documentation site builds on the success of Q&A with the recognition that some things can be done better, listed the following features describing the site:

• Familiar elements, so you're not starting from scratch. Voting, requesting a topic, adding examples all mirror Q&A elements (voting, asking, answering).
• More emphasis on collaboration, and ensuring most developers can contribute. The more canonical nature of artifacts created means:
  • More "shared" ownership of posts and more collaboration.
  • Small edits and contributions are encouraged.
  • Everything is reviewed by other helpers, so you can't "break" the page trying to help.
• More recognition for more people -- More collaboration means more helpers need recognition. And documentation shares a feedback and reputation system with Q&A, so contributions to either earn you reputation and privileges on both.
• Your generosity, your content. All content is covered by the same CC-SA license that SO Q&A always used. And our regular data dumps will now include Documentation content.
• "Be Nice" still applies. We know that occasionally some folks can get a little prickly, but this is who we still are:

  Whether you've come to ask questions, or to generously share what you know, remember that we're all here to learn, together. Be welcoming and patient, especially with those who may not know everything you do. Oh, and bring your sense of humor. Just in case.

Montrose firstbroached the idea for a new Documentation site last August in a post on Stack Overflow Meta, "where users like you discuss bugs, features, and support issues that affect the software powering all 158 Stack Exchange communities." The lengthy post provides all the details about the impetus for the new project.

"Often documentation is lacking in examples, or the examples are trivial and don't demonstrate typical use," Montrose said then. "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."

Developers who embrace it by participating can earn badges, a reward and recognition mechanism used on Stack Overflow. For example, a silver "Documentation Pioneer" badge will be awarded to users who contribute documentation within the next four weeks (and become eligible for one of 100 Stack Overflow T-shirts to be given away).

As befitting a beta, some bugs are still to be worked out in the new site. For example, just this morning a user reported "getting weird errors (like 'title must be entered' pointing at a field that already has a title in it) and then losing my work."

Developers who participate in the new site can help surface such bugs while providing initial community content to fill out the now-skimpy site.

"Whether you've been posting on Q&A for years, or have always wanted to give back if you could, now's your chance," Montrose said. "Docs today resembles Stack Overflow Q&A was right when it launched -- there's a lot of white space to fill in, and plenty of chances to 'actually write the book on' your favorite tech."