There Is No “One-Size-Fits-All” API Docs Experience
There Is No “One-Size-Fits-All” API Docs Experience
Developers use three different approaches to learn new APIs
Developers use different approaches to learn new APIs
Meng, Steinhardt, and Schubert conducted an observational study of developers working to solve programming tasks involving an API. The results reveal differences regarding developer activities and documentation usage that a successful API documentation strategy must accommodate.
What the research uncovered
There is no single developer persona; therefore, there is no “one-size-fits-all” API Docs experience because developers use different approaches to their work. For example, some developers are less willing to read conceptual information, although not reading it often impacts their effectiveness.
Providing all developers with the same API documentation experience is a mistake.
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 three information-seeking software developer personae and the approaches they use when looking for information to put a new API to work.
Three developer learning personae:
Systematic learners — those who seek to understand the API before they use it
Opportunistic learners — those who seek to get started as quickly as possible without first understanding the API or checking the documentation
Pragmatic learners — those who combine elements of both systematic and opportunistic approaches
Characteristics of systematic learners
Researchers Meng, Steinhardt, and Schubert found that devs with a systematic learning approach “wrote code defensively” and “tried to get a deeper understanding of a technology before using it.” These software coders prepared for their work by exploring the API and preparing their development environment before starting.
The researchers discovered some systematic developers started every task with a clean piece of code (located in the code examples section of the docs). Then they used examples (found on the Samples and Recipes pages and in the API reference) to modify the code they started with.
“They seemed to use a similar process to solve each task,” the researchers say. Systematic developers tend to form a hypothesis about the approach and (if needed) clarify terms or concepts they did not fully understand.
The researchers witnessed the devs "in the systematic group carefully “read sections of the documentation and code samples, and, in general, followed the processes and suggestions closely.”
Characteristics of opportunistic learners
Researchers Meng, Steinhardt, and Schubert found that devs with an opportunistic learning approach “worked more intuitively” and “did not follow the processes and suggestions described in the [API] documentation.” Instead, they accessed the documentation only to identify and copy a snippet of sample code, which they modified or extended.
The researchers described developers in the opportunistic group as “highly task-driven” and desiring “fast and direct access to the information.”
They observed that opportunistic devs “did not take the time to get a general overview of the API before starting the first task” and did not read most of the documentation. Instead, they “scanned” it, jumping from page to page without an apparent search strategy, seeming to “deliberately risk” making errors, resulting in their having to check the documentation to overcome errors.