[论文解读] Zur Benutzbarkeit und Verwendung von API-Dokumentationen

Rolf Huesmann, Alexander Zeier+2 more|arXiv (Cornell University)|Jan 1, 2020

Information and Cyber Security被引用 1

一句话总结

本文提出了一种以可用性为重点的加密API文档系统，基于先前研究中的九项关键需求构建原型，并通过22名开发者的用户研究进行评估。研究发现，'快速API使用'是影响最大的需求，其作用涵盖了其他五项需求，而传统参考文档和注释功能的使用率较低，表明在缺乏长期验证的情况下，其即时价值有限。

ABSTRACT

A good documentation is essential for a good usability of (security) APIs, i.e. especially for the correct use of the APIs. Requirements for good documentation of APIs have been described in several papers, but there is no technical implementation (hereinafter referred to as a documentation system) that implements these requirements. The requirements can be divided into requirements for the documentation system and requirements for the documentation content. Out of 13 identified requirements for a documentation system itself, 9 were implemented in a prototype and evaluated in a user study with 22 test persons using a cryptographic API. It turned out that the implementation of the requirement 'Enable quick use of the API' depends on the one hand on the quality of the content entered, but on the other hand also includes 5 other requirements or their implementation. The two other implemented requirements ('classic reference' and 'question and answer function') were hardly or not at all used by the test persons. Their usefulness and relevance should be investigated in a long-term study.

研究动机与目标

• 解决因可用性差的加密API文档导致的安全漏洞这一关键问题。
• 基于先前研究，识别并实现API文档系统的关键可用性需求。
• 通过针对软件开发者的受控用户研究，评估这些需求在实际应用中的有效性。
• 评估特定文档功能（如注释和传统参考）在真实编程任务中的实际效用。

提出的方法

• 开展文献综述，从先前关于开发人员可用性的研究中识别出13项API文档可用性需求。
• 从这些需求中筛选并实现其中九项，构建用于加密API的原型文档系统。
• 设计一项受控用户研究，邀请22名参与者使用eUCRITE和Tink API完成加密编程任务。
• 通过屏幕录制、口头报告法和结构化问卷收集数据，以评估文档的可用性。
• 使用标准化问卷（例如，改编自Acar等人）测量感知可用性、任务完成度和错误恢复能力。
• 通过分析定性反馈和定量评分（例如，1–6分制）来评估功能有效性及整体文档质量。

实验结果

研究问题

• RQ1 实现'快速API使用'需求在多大程度上提升了开发者的任务完成度和感知可用性？
• RQ2 不同文档功能（如代码示例、注释、传统参考）如何影响开发者的参与度和任务表现？
• RQ3 在加密API使用过程中，哪些API文档可用性需求最有效减少错误并提升理解？
• RQ4 开发者如何评价注释系统和传统参考等功能在真实编程任务中的实用性？
• RQ5 文档质量与加密操作正确实现之间存在何种关系？

主要发现

• '快速API使用'需求影响最大，其作用涵盖了其他五项需求，表明其在有效文档中的基础性作用。
• '试用'或'实时代码'功能显著提升了感知可用性，是任务成功的核心要素，尤其在内容质量高的前提下。
• 传统参考和注释功能使用频率极低，表明在短期任务情境中其即时价值有限。
• 参与者对eUCRITE API文档的评分更高（平均分4.2/6），而Tink文档的平均分仅为3.5/6，表明原型文档的可用性更优。
• 只有当错误信息具有实际意义并直接关联到根本原因时，开发者才认为其有帮助，这有助于提升调试效率。
• 参与者表示，清晰、结构良好的代码示例和概念性解释是最有价值的功能，能有效降低认知负荷和实现错误。