Don’t Judge a Book by Its Cover
Don’t Judge a Book by Its Cover
Criticisms aimed at StackOverflow Documentation are not unwarranted, but I would not be so quick to write off this new service.
Join the DZone community and get the full member experience.Join For Free
[Latest Guide] Ship faster because you know more, not because you are rushing. Get actionable insights from 7 million commits and 85,000+ software engineers, to increase your team's velocity. Brought to you in partnership with GitPrime.
StackOverflow has a new documentation feature in beta. This is a natural progression given that, by some accounts, developers are using StackOverflow for 50% of their documentation anyway. But not everyone is impressed with the output being generated:
This is not an unfair criticism, especially from Spring developers as the Spring documentation sets a high standard for open source projects. But I would not be so quick to write off StackOverflow Documentation just yet.
Let’s start with the obvious generalization leveled at developers: they don’t like writing documentation. As a developer myself, I will say that in my experience this is true more often than it is false. Of course, I could say the same about just about every other job title in the average enterprise environment. Most enterprises will have some kind of internal CMS, and the one thing they have in common that enterprise CMSs are where good intentions go to die. Take a look through your own CMS and you’ll quickly realize that the majority of content in it is poorly written and out of date.
The reason is simple: those with the knowledge often have no incentive to devote the incredible amount of effort required to share it in a coherent and comprehensive way. And make no mistake, good documentation does require a significant amount of effort.
What is needed is a middle ground where developers can share their knowledge with a few minutes of work. Ideally, there should be an interface that is as simple as open-edit-save where documentation and clarification of features, code examples, and other concepts can be done without a significant jump out of a developer's day to day workflow. Meanwhile, those who maybe don’t have a deep understanding of the subject matter but who want to contribute anyway can likewise edit the content with the same open-edit-save workflow.
Compare this open-edit-save mentality to the “I know that paragraph is incorrect but I really don’t have any interest in raising a ticket and trying to get the responsible parties to update it” mentality that so often kills contributions to traditional documentation.
StackOverflow Documentation works not because in the short term it will be able to match the quality of a dedicated developer devoting time to documentation which is then edited by a similarly devoted technical writer or editor. In fact, I imagine the first generation of books written in StackOverflow will be little more than FAQs put together by a few enthusiastic contributors.
But give StackOverflow Documentation 5 years and I predict the ease with which people can contribute combined with a huge community and some clever gamification will produce some of the most comprehensive and up to date documentation the technical community has ever seen.
Don’t judge a book by its cover, and don’t judge StackOverflow Documentation by the first generation of books that it produces. If you trust that most people will mostly contribute improvements, then remove the barriers to contributing will eventually lead to better content. It worked for Wikipedia, and it will work for StackOverflow Documentation.
Published at DZone with permission of Matthew Casperson , DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.