In the following article, we invite you to deep-dive into a topic that can help you understand the developer’s world better. This article is a knowledge base that mainly relies on scientific observations, from which we present a summary combined with our experiences. We appreciate both the uniqueness of each individual and the complexity of the developer community as such. The categorization that we present in the following section is a research-based simplification which might serve as an aid to learn about typical patterns observed in the process of API learning. In this article, we will refer to the emerged categories as archetypes.
The contexts for API learning include hobbies, experimentation with technology, completing some minor (e.g. bugfix) or major component of code production, or even owning and developing an API [1]. As diverse as these goals are, so are the developers behind them.
Back in 2007, developers were categorized into three groups based on their approach to learning and coding, with two clearly different groups being the systematic and opportunistic developers, and pragmatic developers having some resemblance to both [2]. The two extremities were observed in scientific research recently [3, 4], indicating that this typology is not something we should forget about.
Developer archetypes
The systematic developer
Systematic developers take a well-educated and defensive approach when coding. They take every precaution they can to protect their code from unstable or untrustworthy processes. These developers amass a deep understanding of technology before using it and pride themselves on building elegant solutions [2].
In the context of API learning, systematic developers will review concepts and architecture documentation to understand the system as a whole and study the individual programming features (e.g. objects, classes, methods and interfaces) to understand how pieces of the system work individually before starting to use them [5].
- They will take time to prepare the development environment. Before starting a task, they will form hypotheses about possible approaches.
- They will follow the proposed processes and suggestions closely, work with a clean piece of code (selected from the code examples), and modify that piece systematically [4].
Since systematic developers will research an API thoroughly before starting a programming task, the act of looking up additional API details later will be a disruption leading to a loss of flow [5]. It is fundamentally important to them to easily locate information in an API reference from the beginning.
The opportunistic developer
Opportunistic developers are curious explorers. They develop just a sufficient understanding of the tech stack to understand how it can solve their current business problem, and delight in solving such problems [2]. They might be highly skillful programmers adopting agile development methods to build applications quickly, or they might be hobby developers or citizen developers (for example scientists writing code to control experiments) [6].
In the context of API learning, they will scan through some of the available documentation pages, check the available tools, and start the task.
- They will depend on reusing code from examples/tutorials or other sources to expedite solution delivery.
- They will work in an intuitive manner that may overlook or deliberately risk errors [4].
On an extreme end, a novice could blindly copy and paste code examples that they find without fully understanding them [7] or even without noticing that the selected code is written in a different code language [8], which would then lead to deleting those parts from the code (since they would not do the job) and starting the whole cycle from the beginning [7]. On a less extreme end, they could try solutions without double-checking in the documentation whether the solutions were correct, and would not follow the processes and suggestions described. They would try things unrelated to the task but possibly helping them build a broader understanding of the API [4].
Often, opportunistic developers will rely on searching the web to find answers rather than resorting to the API documentation on a developer portal or specialized forums. They gather the information they need in parallel to coding, rather than doing one after the other as systematic programmers do [5]. They would do a lot of searches while developing their solution and open many browser tabs as forms of external memory. For this reason, opportunistic developers benefit from organizing their information collections to more easily dismiss or re-find information as their tasks change throughout their coding journey [7] (this could mean grouping browser tabs or pinning favorite documents, etc.)
The pragmatic developer
Their working style combines the elements of the systematic and the opportunistic approaches. They write their code methodically, and develop a sufficient understanding of technology that enables them to use it - but not more (so they don’t necessarily try to understand the bigger picture, or deeply consider the maintainability of the code, etc.). They pride themselves on building robust applications [2].
In the context of API learning, they would learn just enough to start a task and then refer to the documentation and other information resources to solve problems as they encounter them.
Archetypes and contextual influences
These three developer archetypes are more of approaches to learning than personality types. They are also not predetermined by programming skills [2]. Although there might be a preferred and typical approach to learning for a given developer, the same developer might have different approaches on different occasions. Time pressure, future maintenance needs, etc., might affect the way one approaches a problem [6].
Commonalities in API learning
Despite the differences outlined above, in some respects all groups have things in common. For example:
- Developers approach documentation with a problem or task in mind [9]
- They tend to ignore documents that focus on the concepts even though conceptual knowledge facilitates the API learning process [9]
- They all use code samples (albeit in a somewhat different manner)
What content & features do developers need?
Professor Michael Meng and his colleagues have exhaustively researched the topic [3, 4, 6]. According to them, different learners benefit from different features and types of content on a developer portal. Below we highlight some of their guidelines.
Regardless of their approach to work, developers benefit from:
- code examples being presented in small chunks and along with comments that explain what the code is doing,
- conceptual knowledge being presented redundantly and integrated into information resources that developers prefer to use,
- efficient and transparent navigation options with navigation aids enabling them to determine where in the documentation they are,
- powerful search in the API documentation. If implementing a search function is not possible, a workaround solution is to place the content on single pages where the browser’s in-built search can be used,
- API documentation being structured according to categories that reflect the functionality or content domain of the API rather than using categories that signal the type of information provided.
Since systematic developers use a developer portal’s content and features as intended, they benefit from materials explaining the API structure and the rationale behind API design decisions. They also systematically read beginners’ tutorials, and familiarize themselves with the APIs using “Getting Started” documentation.
The opportunistic (and to some extent, the pragmatic) developer deviates from how content is intended to be consumed on the portal. To ensure that their needs are also taken into account, we need to consider the following:
- They would start to work with code immediately. They would often search the web for code snippets, and thus if one wants to direct them to a developer portal, it is of utmost importance to make the portal visible on the web by making them accessible to search engines.
- Once on the portal, these developers benefit from code examples that directly match their problem, or at least serve as a promising starting point. They suffer if the code examples contain placeholders to avoid redundancy - each code example should be complete, they should demonstrate the intended use of the API and they should enable direct reuse via copy and paste. It helps these developers if the text is easily distinguishable from the code (e.g. by separating them into different columns, with a clear alignment between them, and with signaling techniques such as color coding).
Facilitate the API learning: best practices from us
To make the list more exhaustive, we would like to add a few thoughts based on our experience with developer portals.
Developers benefit from a clear and concise API documentation that states language, assumptions and limitations clearly. To reflect on this need, Zero Gravity developer portals allow for both machine-generated code samples and code samples provided by the OpenAPI specification, and they can be easily copied or downloaded by clicking on an icon. In the case of OAS documentation, generated code samples can be available in several programming languages and a selector allows developers to choose the preferred one. Syntax highlighting makes code details easier to understand and transparent. These reduce the risk of copying and pasting code samples that are not a good fit or require much rework to fit the developer’s desired use case.
Clearly outlining all of the possible use cases for an API through documentation or SDKs also benefits developer’s adoption and continued use of your API products. Outlining limitations saves these developers from the work involved in troubleshooting when the API does not in fact meet their expectations or specific requirements. With Zero Gravity developer portals, APIs can be flexibly documented by linking content together and displaying them on different tabs related to the same API. This makes it particularly easy to accommodate use cases, tutorials, examples and the like.
Developers benefit from support, community, and forums because they can ask questions once they have reached the limits of what the documentation (and their own code) allows them to complete. On Zero Gravity portals, developers are supported by FAQs, contact forms, and general documents such as “Get started”. The blog section can be a highlight for the community, especially if members are allowed to showcase their work and solutions.
By anticipating and designing for a diverse audience, you can ensure that developers have a good user experience regardless of their skill level and working style.
Do you need help with your developer portal? If you can use professional help with improving user experience and increasing value for your users, get in touch with us.
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
References
- [1] Robillard, M. P., & DeLine, R. (2011). A field study of API learning obstacles. Empirical Software Engineering, 16(6), 703-732.
- [2] Clarke, S. (2007). What is an end user software engineer?. In Dagstuhl Seminar Proceedings. Schloss Dagstuhl-Leibniz-Zentrum für Informatik.
- [3] Meng, M., Steinhardt, S., & Schubert, A. (2018). Application programming interface documentation: what do software developers want?. Journal of Technical Writing and Communication, 48(3), 295-330.
- [4] Meng, M., Steinhardt, S., & Schubert, A. (2019). How developers use API documentation: an observation study. Communication Design Quarterly Review, 7(2), 40-49.
- [5] Watson, R. B. (2015). The effect of visual design and information content on readers’ assessments of API reference topics (Doctoral dissertation).
- [6] Brandt, J., Guo, P. J., Lewenstein, J., Dontcheva, M., & Klemmer, S. R. (2009, April). Two studies of opportunistic programming: interleaving web foraging, learning, and writing code. In Proceedings of the SIGCHI Conference on Human Factors in Computing Systems (pp. 1589-1598).
- [7] Gao, G., Voichick, F., Ichinco, M., & Kelleher, C. (2020, August). Exploring programmers’ api learning processes: Collecting web resources as external memory. In 2020 IEEE Symposium on Visual Languages and Human-Centric Computing (VL/HCC) (pp. 1-10). IEEE.
- [8] Dorn, B., Stankiewicz, A., & Roggi, C. (2013). Lost while searching: Difficulties in information seeking among end-user programmers. Proceedings of the American Society for Information Science and Technology, 50(1), 1-10.
- [9] Meng, M., Steinhardt, S. M., & Schubert, A. (2020, October). Optimizing API Documentation: Some Guidelines and Effects. In Proceedings of the 38th ACM International Conference on Design of Communication (pp. 1-11).
