Understanding How Programmers Can Use Annotations on Documentation

Document Title

Understanding How Programmers Can Use Annotations on Documentation

Document Information

• Subject Area: Software Engineering, API Documentation Usage and Learning, Annotation System Design and Evaluation
• Keywords: Annotation System, Software Engineering, Application Programming Interface (API), Documentation, Note-Taking

Research Background and Issues

• Identified Problems or Challenges:

  • API documentation is often difficult to use, with issues such as incompleteness, ambiguity, and inaccuracies, which hinder developers from learning and using APIs effectively.
  • Developers lack effective means to share the knowledge they gain after overcoming documentation challenges.
  • Developers frequently take notes while learning APIs, but existing tools do not adequately support this behavior.
  • Community Q&A platforms (e.g., Stack Overflow) can help solve problems but may be suboptimal due to the lack of contextual information.

• Significance:

  • Software developers rely on API documentation to understand functionality and use new libraries or tools, making documentation quality critical for development efficiency and code quality.
  • Providing a mechanism to help developers record and share documentation-related information can enhance individual learning efficiency and foster team collaboration.

• Research Motivation and Related Work:

  • Previous studies on API learning barriers highlight the urgent need for documentation improvement.
  • Analyzing developers' note-taking behavior and existing annotation systems to explore the potential of annotation features in addressing documentation issues.

Solution

• Proposed Solution:

  • Developed the Adamite browser extension, designed to support developers in annotating key information on API documentation and assisting them in organizing and sharing notes.
  • Supported annotation types include general comments, questions, resolved issues, documentation issue types (e.g., fragmented information, inaccuracies), task annotations, and a "multi-anchor" feature.
  • The system provides search, filtering, and pinning functionalities, enabling users to quickly locate critical annotations.

• Innovations:

  • Introduced categorized annotation types, allowing users to create more structured and context-rich notes (e.g., question annotations, task annotations).
  • Added a multi-anchor feature, enabling a single annotation to link multiple document fragments.
  • Supported issue tracking functionality, allowing users to mark problem resolution status and follow-ups.

• Implementation Steps and Key Technologies:

  • Adamite is built using React and Firestore, with annotations stored in JSON format and synchronized in real-time.
  • Interaction with documentation is achieved through XPath for precise annotation positioning.
  • Integrated Elasticsearch to support full-text search, enhancing content discovery efficiency.
  • Features such as "pinned annotations," annotation grouping, and replies promote efficient annotation utilization and user collaboration.

Research Outcomes

• Specific Outcomes:

  • Users can create useful annotation records that benefit both themselves and other developers reading the annotations later.
  • Annotation readers performed significantly better in completing designated API learning tasks compared to the control group without annotations.
  • The most effective annotations were concise explanations of code or problem-solving content.
  • Annotation types (e.g., question-type annotations) helped users more easily manage unresolved content in the documentation.

• Advantages Compared to Existing Solutions:

  • Compared to Q&A platforms, annotations provide more specific and contextualized information.
  • Customizable annotation features combined with robust tool support address documentation usability issues effectively.

• Experiment and Evaluation Results:

  • Experimental results showed a 67% improvement in task completion efficiency with annotated documentation.
  • Experiments demonstrated that annotations are particularly effective in addressing issues such as fragmented, ambiguous, incomplete, and incorrect documentation content.
  • The average annotation length was short (approximately 9.31 words), significantly reducing recording costs and improving recording efficiency.

• Limitations and Future Directions:

  • Limitations: Adamite is unsuitable for dynamic pages or PDF files, and annotations may become invalid due to documentation or API updates.
  • Future Directions:
    • Develop similar annotation tools for integrated development environments (IDEs) to facilitate in-code learning.
    • Explore anchor stability and annotation longevity in dynamic scenarios.
    • Extend research on technology transfer to other domains (e.g., travel planning or electronic product selection).

Conclusion

This paper proposes an annotation-based solution to help developers address common issues with API documentation. The Adamite tool demonstrates the potential of annotations in recording, learning, and sharing task knowledge during development, as well as improving documentation problem-solving efficiency. Future work will further investigate the real-world impact of annotations and documentation improvements, along with tool optimization.