Embed Size (px)
DESCRIPTION
How do software developers learn about APIs?
Citation preview
Crowd Documentation How Programmer Social
Communities are Flipping Software Development
Chris Parnin, PhD Candidate @ GT@chrisparnin ninlabs.com checkbox.io
About MeMy “other thesis”
Types of Documentation
Types of Documentation
Software documentation is created by a few and read by few.
Types of Documentation
Software documentation is created by a few and read by few.
API documentation is created by a few and read by many.
API Documentation is Big Business
http://thirdblogfromthesun.com/2010/09/how-big-is-the-msdn-library/
Is costly to create
It sucks, the documentation sucks, the examples are ridiculous. This is part of the reason there are so many junk apps on android as well. iOS stresses interface and user experience from the first time you open the dev portal, android... do they ever even mention it? Not that I have seen. Its all obscure code stuff and external libraries created by who knows who etc.
http://forum.unity3d.com/threads/104567-iOS-vs-Android-from-a-dev-perspective/page2
Help win platform wars
APIs as the new business model
• Twilio
• Stripe
• Coinbase
//require the Twilio module and create a REST clientvar client = require('twilio')('ACCOUNT_SID', 'AUTH_TOKEN');client.makeCall({ to:'+16515556677', from: '+14506667788', url: 'http://www.example.com/twiml.php'}, function(err, responseData) { console.log(responseData.from); // outputs "+14506667788"});
4000 pages of documentation
Traditional Forms
4000 pages of documentation
Traditional Forms
What are the sources of dev knowledge now?
Unofficial Microsoft SurveyWhen learning about API documentation % of
following resource is used “Often”
Unofficial Microsoft Survey
73.5% (2,224)
When learning about API documentation % of following resource is used “Often”
Unofficial Microsoft Survey
73.5% (2,224)
42.5% (1,289)Code completion (IntelliSense)
When learning about API documentation % of following resource is used “Often”
Unofficial Microsoft Survey
40.1% (1,212)Microsoft’s Official Documentation
73.5% (2,224)
42.5% (1,289)Code completion (IntelliSense)
When learning about API documentation % of following resource is used “Often”
Searching for Documentation
Examine search results of jQuery
blog >
StackOverflow >
unofficialdoc >
... 1730 search results
>
Crowd Documentation
Knowledge is created and curated by a mostly uncoordinated collective.
What sources do devs actually use?
A day of a dev
...1,316 days of developer browser history
Typical dev >
Typical dev >
DirectDirect
Typical Flow: C-Q Monitor Flow: A-B
64%22% 2%
48%28% 38%39%
22% 1% 26%
56%18%
18%
18%
Consistent with self-reported surveys.
What makes it different?
Twice as many examples can be found on Stack Overflow than the official documentation guide.
• Developers may be getting as much as 50% of their documentation from Stack Overflow.
• More examples can be found on Stack Overflow than the official documentation guide.
• In web searches, Stack Overflow questions are visited 2x-10x more often than official documentation.
User participation
0%
20%
40%
60%
80%
100%
0 20 40 60 80 100
Pe
rce
nt
of
Co
ntr
ibu
tio
ns
User Percentile
0%
20%
40%
60%
80%
100%
0 20 40 60 80 100
Pe
rce
nt
of
Co
ntr
ibu
tio
ns
User Percentile
Android
0%
20%
40%
60%
80%
100%
0 20 40 60 80 100 Pe
rce
nt
of
Co
ntr
ibu
tio
ns
User Percentile
Askers
Advisors
GWT Java
User participation
60% of questions answered by 5% of users.
Diminishing game mechanisms
2 years to reach 80% coverage
Failure of online communities
Encouraging User Behaviour with Achievements: An Empirical Study Scott Grant and Buddy Betts
http://michael.richter.name/blogs/why-i-no-longer-contribute-to-stackoverflow/
What did developer’s think?
But then...everything you thought you knew
was wrong
“DLLs are tossed over the fence to English majors”
“We sometimes take a break from documentation and try building something for a month or two. Then we realize how bad it is”
“We contact the top 100 Stack Overflow contributors”
“Documentation isn’t meant to be read by everyone, it’s meant to be authoritative”
“You don’t understand how much this has impacted us. No, really you don’t.”
Stakeholders Concerns
• Will we have a job in 5 years?
• What should our voice be?
• How can we "regain" authority over the crowd (e.g. people suggesting unsupported/non-public API methods in android development). [*]
• Getting feedback from the crowd: sentiment analytics over the frustrating parts, frequent questions, confusing topics, etc.
* https://code.google.com/p/android/issues/detail?id=62220
Why not participating?
Bar/coffee interviews
“I don’t blog because I fear being wrong on the internet... I share gists, or fix documentation and then tweet about it.
Blogs are disconnected from official sources, like project documentation. I can't imagine someone reading what I write. I would rather associate the content with the documentation.”
“About 2 years ago, I used to answer a lot more. But now, it feels like most questions have already been
answered -- it is saturated. That might change when something new comes out, some of the newer stuff we
started working on, I might have a chance to answer questions on it.”
Massively distributed software engineering
At our current place, imagine how these would fare if needed in a few years:• A government api to calculate taxes on all online purchases for any location?• A distributed traffic regulation system for a network of self-driving cars and
drones.• ...
In the next 50 years, as governments increasingly turn legal policy and services into source code and public APIs, often created in the timespan of a president’s term, we must be prepared to build massively-sized software systems on a regular basis. This will often require cooperation of many diverse stakeholders.
health care insurance marketplace
two decades
Crowd Programming
• We have seen “crowd documentation” how might the other pieces look like?
Rather than having a rich standard API, Javascript essentially has a “crowd API” assembled from Stack Overflow snippets and Github repositories.
