Here are a few reasons why Stack Overflow’s Documentation effort failed:
Now, to make sense of the failure for technical writers. Was Stack Overflow’s Documentation good or bad for professional technical writers? I think the failure has both good and bad results.
Evidence against crowdsourcing. Stack Overflow is one of the most successful sites that programmers consult to find needed information. It has a functional gamification model that incentivizes many contributors. If any attempt at crowdsourcing docs could have worked, it would have been with Stack Overflow. That it failed presents us with a compelling argument that crowdsourcing docs, no matter the platform or topic, is an idea that doesn’t work. We can stop trying this model with the latest technology that sells itself on how easy it is for everyone to contribute. Whether it’s a new wiki or an Edit on Github button, crowdsourcing docs (beyond simple fixes of typos and broken links) doesn’t work.
Job security. We’re not going to be crowdsourced out of a job soon. There was a fear that companies would simply start a product category on Stack Overflow, and programmers and others would flock to the site to create the needed documentation. If that would have truly happened, my role as a technical writer would have been either eliminated or reduced to content curation and error correction. Stack Overflow’s Documentation failure also reinforces the difficulty of the technical writer’s role, which drives up our value. It’s not easy to create compelling, clear, and helpful documentation, and people won’t just create doc for free. Good documentation continues to remain a struggle on open source projects as well. Technical writing really is hard, and it’s hard to find good technical writers.
Existing doc model is okay. The examples-before-explanations model won’t cause us to re-architect all of our documentation. If this model had won out (and persuaded users to go to Stack Overflow instead of the original sources), it might have caused tech writers to rethink and reapproach all of our existing documentation. Since this didn’t happen, perhaps it’s okay to lead with an explanation before an example.
Missed out on Wikipedia for tech docs. If the model had worked, Documentation could have turned out to be an incredible resource for the Internet, on par with Wikipedia but with tech docs. This could have been the first fully functional crowdsourcing model for documentation. Given how influential Wikipedia has been at distributing and disseminating information, we could really use a similar model with documentation, which has traditionally been seen as “terrible” and a “waste of time” by many users.
Missed out on industry standard doc platform. We might have abandoned all our fragmented tools and just started using Stack Overflow’s platform for documentation. This could have eliminated a lot of tool tinkering and inefficiency while introducing a standard industry-wide platform and format for tech docs. Users would have had a central location to turn to for documentation.
Not forced into more interesting careers. If Documentation had ended the careers of technical writers, we could have potentially transitioned into more interesting lines of work. I’ve always wanted to join the CIA, military, or police force. If tech writing had been seriously threatened by the Stack Overflow Documentation model, it might have forced me to look elsewhere. As is, I’ll probably just keep my boring ol’ tech writer job. (I’m mostly kidding here. I love writing docs.)
How could the Stack Overflow Documentation effort be tweaked in order to be successful? More interestingly, why was Wikipedia, another information crowdsourcing effort, successful in contrast? What characteristics led to Wikipedia’s success that Stack Overflow could adopt to achieve similar success?
These are the questions everyone wants to know when it comes to crowdsourcing, and I by no means have the answers.
On Niemanlab.org, Megan Garber summarizes scholar Benjamin Mako Hill’s work on this topic. Garber explains:
Wikipedia attracted contributors because it was built around a familiar product — the encyclopedia. Encyclopedias aren’t just artifacts; they’re also epistemic frames. They employ a particular — and, yet, universal — approach to organizing information. Prior to Wikipedia, online encyclopedias tried to do what we tend to think is a good thing when it comes to the web: challenging old metaphors, exploding analog traditions, inventing entirely new forms… But that approach, web-native and admirable as it was in theory, ended up hindering early encyclopedias’ ability to attract contributors. — The contribution conundrum: Why did Wikipedia succeed while other encyclopedias failed?
That Stack Overflow tried to reinvent the documentation format in an unfamiliar model (not just examples first, but upvoting topics and surfacing more popular topics), may have contributed to its lack of success. Any time you present a new mental model, you also risk alienating a user base who already has an idea of what they’re looking for. (But this is the risk inherent in any innovation.)
Stack Overflow shouldn’t consider the information in their forums as something other than documentation. Stack Overflow’s forums provide helpful documentation for niche cases. Mark Baker regularly champions Stack Overflow as a model for successful “Every Page Is Page One” documentation.
Perhaps instead of trying to introduce a new model, Stack Overflow should build on their existing forum model to make the information more valuable and documentation-like. Some ways they could improve their forum documentation might be as follows:
Now that the Documentation experiment is over, I’ll be interested to see what innovations Stack Overflow follows next. I can’t say that I participated much in Documentation or used it, but it was awesome to see the effort and interesting to interpret the result.
To read more on this topic, see Beth Aitman’s post Thoughts on Stack Overflow’s Documentation beta. See also Bob Watson’s thoughts in It’s hard to write good technical docs, Learning from V1, and Still buzzing about Stack Overflow documentation.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in , API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.