[論文レビュー] 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の使いやすさに焦点を当てたドキュメント管理システムを提案し、先行研究から抽出された9つの主要要件をプロトタイプに実装し、22名の開発者を対象としたユーザースタディで評価した。スタディの結果、'迅速なAPI使用'が最も効果的で、他の5つの要件を統合しており、古典的リファレンスやコメント機能は低利用率にとどまり、長期的検証なしでは即時の価値が限定的であることが示唆された。

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ドキュメントシステムに必要な使いやすさ要件を同定し、実装すること。
• ソフトウェア開発者を対象とした制御されたユーザースタディを通じて、これらの要件の実効性を評価すること。
• コメント機能や古典的リファレンスのような特定のドキュメント機能が、実世界のプログラミングタスクにおいてどれほど実用的であるかを評価すること。

提案手法

• 開発者ユーザビリティに関する先行研究から、APIドキュメントにおける13の使いやすさ要件を同定するための文献レビューを実施した。
• そのうち9つの要件を選び、暗号化API向けのプロトタイプドキュメントシステムに実装した。
• eUCRITEおよびTink APIを用いた暗号化プログラミングタスクを解決するための、制御されたユーザースタディを設計した。
• スクリーンレコーディング、考えながら話すプロトコル、構造化されたアンケートを用いて、ドキュメントの使いやすさを評価するデータを収集した。
• 標準化されたアンケート（例：Acarらのものに適合）を用い、認識された使いやすさ、タスク完了度、エラー回復能力を測定した。
• 定性的フィードバックと定量的評価（例：1〜6段階の評点）を分析し、機能の有効性および全体的なドキュメント品質を評価した。

実験結果

リサーチクエスチョン

• RQ1 「迅速なAPI使用」要件を実装することで、開発者のタスク完了度と認識された使いやすさはどの程度向上するか？
• RQ2 コード例、コメント、古典的リファレンスなどの異なるドキュメント機能は、開発者の関与度とタスクパフォーマンスにどのように影響するか？
• RQ3 暗号化API使用の際、エラーの低減と理解の向上に寄与する、APIドキュメントの使いやすさ要件の中で最も効果的なものは何か？
• RQ4 開発者は、コメントシステムや古典的リファレンスのような機能を実世界のプログラミングタスクにおいてどれほど有用だと感じるか？
• RQ5 ドキュメントの質と暗号化操作の正しく実装される確率との間にどのような関係があるか？

主な発見

• 「迅速なAPI使用」要件が最も効果的で、他の5つの要件を統合しており、効果的なドキュメントにおける基盤的役割を果たしていることが示された。
• 「試してみる」または「ライブコード」機能は、認識された使いやすさを著しく向上させ、特に高品質なコンテンツと組み合わせられた場合、タスク成功の中心的役割を果たした。
• 古典的リファレンスおよびコメント機能はほとんど使用されておらず、短期間のタスク文脈では即時の価値が限定的であることが示唆された。
• 参加者たちはeUCRITEのAPIドキュメント（平均評点4.2/6）をTinkのドキュメント（平均評点3.5/6）よりも高く評価しており、プロトタイプにおける使いやすさの優位性が示された。
• エラーメッセージは、意味があり、根本原因に直接関連している場合にのみ役立つと認識され、デバッグ効率が向上した。
• 参加者たちは、明確で整理されたコード例と概念的説明が、認知的負荷の低減と実装エラーの低減に最も価値があると報告した。