Understanding How Programmers Can Use Annotations on Documentation
Amber Horvath, Michael Xieyang Liu, River Hendriksen, Connor Shannon,, Emma Paterson, Kazi Jawad, Andrew Macvean, Brad A. Myers

TL;DR
This paper explores how annotations on documentation can improve API understanding and sharing among developers, introducing a tool and demonstrating its effectiveness through a user study.
Contribution
It presents Adamite, a novel annotation tool supporting multi-anchoring and annotation types, and provides empirical evidence of its benefits in API learning.
Findings
Developers can create useful annotations for themselves.
Annotations help others learn APIs more effectively.
Readers completed 67% more of the task with annotations.
Abstract
Modern software development requires developers to find and effectively utilize new APIs and their documentation, but documentation has many well-known issues. Despite this, developers eventually overcome these issues but have no way of sharing what they learned. We investigate sharing this documentation-specific information through \textit{annotations}, which have advantages over developer forums as the information is contextualized, not disruptive, and is short, thus easy to author. Developers can also author annotations to support their own comprehension. In order to support the documentation usage behaviors we found, we built the Adamite annotation tool, which supports features such as multi-anchoring, annotation types, and pinning. In our user study, we found that developers are able to create annotations that are useful to themselves and are able to utilize annotations created by…
Peer Reviews
No public reviews on file for this paper yet. If you reviewed it on a platform where reviews are public (OpenReview, ICLR, NeurIPS, ICML), you can paste yours below so the community can read it here.
Videos
No videos yet. Explain this paper in a talk, walkthrough, or lecture? Add one.
Taxonomy
TopicsSoftware Engineering Research · Open Source Software Innovations · Software Engineering Techniques and Practices
