理解程序员如何在文档中使用注解

文献标题

Understanding How Programmers Can Use Annotations on Documentation

文献信息

• 主题领域: 软件工程、API文档使用与学习、标注系统设计与评价
• 关键词: 标注系统、软件工程、应用程序接口 (API)、文档、笔记记录

研究背景与问题

• 发现的问题或挑战:

  • API文档通常难以使用，内容存在不完整性、模糊性、不正确性等问题，导致开发人员学习和使用API时受到阻碍。
  • 开发人员通常克服文档问题后，无有效途径分享自己学到的信息。
  • 开发人员在学习API时常会记录笔记，但现有工具未充分支持这种行为。
  • 社区问答平台（如Stack Overflow）虽然有助于问题解决，但因缺乏上下文而可能不够理想。

• 重要性:

  • 软件开发人员依赖API文档理解功能和使用新的库或工具，文档质量对开发效率和代码质量具有重要影响。
  • 提供一种机制帮助开发人员记录和共享文档相关信息，不仅可以提升个人学习效率，还能促进团队协作。

• 研究动机与相关工作:

  • 研究既往API学习障碍因素显示文档改进需求迫切。
  • 分析开发人员的笔记行为和现有标注系统，探索结合标注功能解决文档问题的可能性。

解决方案

• 提出的解决方法:

  • 开发了 Adamite 浏览器扩展，专用于支持开发人员在API文档上标注关键信息，并帮助开发人员组织和共享笔记。
  • 支持标注类型包括普通注释、问题、问题已解决、文档问题类型（如片段信息、不正确信息）、任务注释，以及"多锚点"功能。
  • 系统提供搜索、过滤、固定标注功能，允许用户快速定位关键标注。

• 创新之处:

  • 引入标注类型分类，使用户能够创建更结构化和上下文化的笔记（如问题注释、任务注释）。
  • 增加多锚点功能，允许一个标注连接多个文档片段。
  • 支持问题追踪功能，可标记问题解决状态及后续关注。

• 实施步骤与关键技术:

  • Adamite基于React和Firestore技术构建，用户的标注以JSON形式储存，并具有实时同步机制。
  • 与文档交互通过XPath实现精准的标注定位。
  • 整合Elasticsearch，支持全文检索以提升内容发现效率。
  • 提供功能如"固定标注"、标注分组和回复，促进标注的高效利用和用户间协作。

研究成果

• 具体成果:

  • 用户能够创建有用的标注记录，既对自己有益，也对后来阅读这些标注的开发人员有帮助。
  • 标注阅读者在完成指定API学习任务时表现明显优于没有标注的实验组。
  • 最有效的标注是短小精悍的代码解释或问题解决类型内容。
  • 标注类型（如问题类型注释）帮助用户更容易管理文档中待解决内容。

• 与现有解决方案的优势比较:

  • 与问答平台相比，标注能提供更具体到位的上下文信息。
  • 可定制化的标注功能结合良好的工具支持解决文档易用性不足的问题。

• 实验与评估结果:

  • 实验结果表明，使用标注后的文档任务完成效率提升67%。
  • 实验表明标注在解决文档片段化、模糊性、不完整及错误内容等问题时效果突出。
  • 标注内容的平均字数短（约9.31字），显著降低了记录成本，提高了记录效率。

• 局限性与未来方向:

  • 局限性：Adamite不适合动态页面或PDF文件，并且标注可能因文档或API更新而变得失效。
  • 未来方向：
    • 开发用于集成开发环境（IDE）的类似标注工具以促进代码内学习。
    • 在动态场景探索锚点稳定性及标注长期有效性。
    • 扩展用于其他领域（如旅游规划或电子产品选择）的技术迁移研究。

总结

本文提出了基于标注功能的解决方案帮助开发人员应对API文档的普遍问题；Adamite工具展示了标注在开发中记录、学习和共享任务知识的潜力，以及文档问题解决效率。未来工作将进一步实现在真实世界中的标注和文档改进效果的研究与工具优化。