1. Crowdsourcing of API Documentation: A Preliminary Investigation,
Allahbaksh M. Asadullah
Infosys Limited, Bangalore
Shilpi Jain
FORE School of Management

2. API Documentation Also known as Programmer’s documentation
It is a deliverable of technical writing in which a writer develops instructions about how to effectively use a Software API, Hardware API or Web API.
A quick reference guide to understand ‘how to use a library or work with the program.’
It details functions, classes, methods, return types and more.
It is often embedded within the source code like Javadoc comments in Java.

3. Software Life Cycle
The requirement keeps on adding in Agile but for all requirement you still Design

4. Time Spent on Initial Development vs. Maintenance
The amount of time spent in Agile remains same. Only the activity names are different

5. For all Practical Purposes……
Maintenance is the key

6. Different Types of Software Maintenance
Involves majorly ‘bug fixes’ and correcting some of the design sections
Corrective
Adaptive
Porting of software to adapt to changing environment and migrate to different versions of tools and library
To enhance features and make software scalable
Scalability
Preventive
Documentation of available features, creating test cases, and predicting risky files

7. When Problems are Severe?
Contract changed among several vendors
Code is not in Sync with the Documentation or architecture changes
Company X
Remove Documentation let the other company suffer

8. Examples - Inappropriate Documentation
Function name:
get Col.
“Is it get column or get Colonel?”
It is difficult for any programmer to interpret the actual meaning…..
Irrelevant presence of commented – code, which makes the reading complex

9. Research Questions
To evaluate and compare the performance of Amazon Mechanical Turk (MTurk) with two in-house developed tools (Eturk and DocIt).
The other objective is to test whether they can produce consumable APIs.

10. API Documentation Tools
Amazon Mechanical Turk (Mturk)
MTurk is one of the services offered by Amazon Web Services.
A crowdsourcing Internet marketplace that enables individuals and businesses to collaborate and perform complex tasks that computers are unable to conclude.
A user of Mechanical Turk can be either a "Worker" (employee) or a "Requester" (employer).
ETurk – Similar to Mturk
Was developed for proprietary software applications.
Unlike MTurk, in E-Turk, the users were allowed to view all HITs, the source code was rendered with highlighted syntax which makes it easier to comprehend, and submission of the task is easy
DociT – A superset of Eturk
Enable to develop a connection between similar classes & methods semantically.
The tool can browse, search and navigate the source code online.
It featured semantic search and gives information on related method and classes (Quite similar to Eclipse)

11. Research Design
Phase 1
Phase 2
Experiment study where software developers wrote API documentation on MTurk and customized prototypes
Preliminary investigation using surveys with software programmers

12. There is more to it….the CORE PROBLEM
I am an architect I don’t want to do this
It is a waste of time
How do I escape from Documentation
It’s not my job..Hire a document Writer
So you caught me as you didn’t find anyone

13. Phase 1

14. Question 1.

15. Question 2. 86% of the developers follow naming conventions.
It was observed that if we provide class and methods both, the worker can comprehend code to create some API documentation

16. Question 3

17. Question 4
Comments
Since projects have stricter deadlines, the focus remains on adding features and delivery
Documentation is a time consuming process and does not give immediate business benefits.
In most of the cases hard deadlines doesn’t provide any room for it.
Frequent changes in requirements completely shifts the focus from the documentation

19. The Architecture diagram of the System
1. Extraction of source code elements and related artifacts from version control system (VCS).
2. The source code is then parsed and a CSV File and Index file is prepared.
3. Artifacts are provided to the crowd developers via Mechanical Turk, ETurk, and DocIt.
4. Devs. wrote API documents.
5. API documents were evaluated by a handful of experienced system architects.
6. Once approved, the source code was updated and committed
to the version control.
VCP – Version control Pulgin
JDT – Java Development Tools
SCP – Source Code Parser
CSV – Comma Separated Values file

20. Crowd Sourcing of API documentation
Mechanical Turk is marketplace for mundane tasks
Mechanical Turk provides a way to submit and carryout multiple HIT(Human Intelligent Task )
These tasks are performed by Humans for small monetary benefits
To chose an appropriate worker the creator of task can design a test
The HITs are independent of each other and can be executed by multiple workers which improves the quality

21. 01 02 03 04 i DocIt Mechanical Turk TwinText and Doc-O-Matic E-Turk
Mimic M-Turk but will have large reach within organization
E-Turk
Provides an IDE like Look and Feel
Provides Cross References
Search Features to find out related code
Provides easy to document way
Large number of workers
Difficult to get very good Java programmers in the M-Turk system
Mechanical Turk
Produces Garbage Documentation or documentation based on Method name
TwinText and Doc-O-Matic
Combination of an IDE and E-Turk
DocIt

22. Findings Documentation through crowd sourcing is achievable.
Development of API documentation by crowd sourcing saves time and effort.
Comparatively, developers spent lesser amount of time and effort in documenting a code where modules are interacting using APIs.
A small chunk of developers have been reviewing API documentation and preparing final output through code review system.
Selection of developers for the documentation need screening at least at two levels:
knowledge of programming paradigm
Domain of the project.
An opportunity for the software industry and academia to evolve and generate new software systems and innovate rapidly.
STUDY IN PROGRESS
Exploring further additional artifacts that could be helpful in documentation.
Experimenting with unit test cases and version commit messages.

23. Thank You