Barriers In API Documentation That Hinder Developers
Barriers In API Documentation That Hinder Developers
Developers benefit from consistency in navigation, predictable structure, useful search, and easy to reuse code samples.
In the January 2019 issue of Communication Design Quarterly, the peer-reviewed research publication of the Association for Computing Machinery Special Interest Group for Design of Communication, the researchers explore how developers use API Docs and identify barriers to developer success using documentation.
The four barriers discussed include:
Inconsistency in navigation — Inconsistent navigation causes some developers to conclude that the documentation is incomplete. Inconsistencies in navigational elements from page to page introduce confusion. Navigational difficulties occur when a developer wants to revisit previously accessed content but can’t figure out how to do so.
Inability to find information by browsing — Developers experience difficulties browsing for information, especially when encountering pages with vague labels that don't accurately describe the page's information. Unclear labels can hinder developers' ability to effectively understand and utilize the API by increasing their cognitive load. Unclear labels require additional mental energy to decipher the purpose and content of each page.
Lousy search — Some sets of API documentation do not provide search. Others offer a rudimentary — but less-than-useful — search that fails to help developers quickly find the information they need. While some developers rely on the built-in on-page search available in most web browsers, those searches may fail to prove useful because API documentation is often distributed over multiple web pages.
Dirty code samples — Developers rely on — and reuse — code samples in API documentation. Efficient reuse of code relies on the sample being clean (e.g., correct, clear, concise, maintainable, and easy to comprehend) and devoid of extra, irrelevant, or invisible code introduced unintentionally while copying the code from its source. Additionally, using placeholders (referencing other code examples) to eliminate redundancy makes it impossible for devs to reuse code via copy and paste quickly.
