Let’s Bring Science Into API Documentation

In today’s fast-paced development environment, effective API documentation is not just nice to have; it’s a necessity. This blog post explores how understanding pattern recognition and learning styles can revolutionize the way we create API documentation. By examining the different types of knowledge present in API references and catering to diverse developer learning strategies, we can create documentation that is not only informative but also engaging and intuitive. 

This blog post stems from Lana Novikova’s presentation at the apidays Paris conference – a central hub and one of the biggest events for all things API. Lana is a product manager for JetBrains Writerside and has over 10 years of experience in technical writing, including API documentation.

Pattern recognition

Neuroscience reveals a fascinating truth: Our brains are expert pattern detectors. We excel at identifying, interpreting, and connecting information, even when encountering it for the first time. This inherent skill, known as pattern recognition, holds significant implications for API documentation, which has a strict structure reflecting the API’s architecture.

In their study Patterns of Knowledge in API Reference Documentation, researchers Walid Maalej and Martin P. Robillard conducted an interesting experiment where they scrutinized API reference documentation for JDK 6 and .NET 4.0. Within these documents, they discovered 12 different “knowledge types” (a specific category of information that users may seek when interacting with an API), including functionality and behavior, directives, and purpose and rationale.

They also identified a “non-informational” knowledge type, i.e., uninformative, repetitive text that serves no actual purpose. 

The study highlighted significant variations in the distribution of these knowledge types across the two documentation sets, suggesting that different APIs might prioritize different types of information. For instance, JDK documentation leans toward conceptual knowledge, while its .NET counterpart emphasizes API structure and usage patterns.

As technical writers, we can harness these findings to create more efficient documentation. Here’s how:

1. Evaluate your API documentation through the lens of these knowledge types. Are certain types overrepresented or missing? 
2. Develop and use documentation templates tailored to the knowledge type typically associated with specific API elements.

Many products, including Writerside, offer ready-made templates for document creation. Here, I want to express my appreciation for The Good Docs project, which maintains an excellent template library for various knowledge types. If you’re interested in using or contributing to these templates, you’re most welcome to do so! We are also discussing a partnership with The Good Docs project, and we will soon announce something exciting together. Stay tuned! 

Writerside includes an out-of-the-box API project template that proposes a boilerplate API project structure and includes an API overview, a quick start guide, a reference section, and a changelog page. You can jump-start your API docs project using this template and then tailor it to your specific use case.

Learning styles

Just like a good teacher adapts their methods to different students, effective API documentation should cater to diverse learning styles. Recognizing these individual preferences is crucial for making the learning process smoother and more enjoyable.

Michael Meng, Stephanie Steinhardt, and Andreas Schubert’s research reinforces this point. Their study observed how developers interact with unfamiliar APIs, revealing distinct approaches based on individual learning styles. Understanding these approaches can help us tailor documentation to better meet developers’ needs.

The research shows that developers spend nearly as much time reading documentation (49%) as they do coding (51%).

Furthermore, developers tend to rely on API references, recipes, and samples as their go-to resources when using API documentation. This preference indicates that practical usage guides are more valuable to developers than abstract concepts. The study also revealed considerable variation among participants regarding the time allocated to individual content categories, which further emphasizes the diversity in learning styles and information-seeking behaviors.

From their findings, Meng, Steinhardt, and Schubert identified three developer personas, each with distinct information-seeking strategies for learning new APIs:

• Systematic learners seek to understand the API and the entities it operates before using it.
• Opportunistic learners aim for the quickest start without prior understanding or documentation review.
• Pragmatic learners combine elements of both systematic and opportunistic approaches.

It’s important to note that a learning style is not a label or a tool for categorization, but rather an individual’s preferred approach to learning, which we should respect and take into account. Behavioral diversity keeps the ecosystem dynamic, and recognizing it in API documentation could be the key to resonating with a broader audience.

Applying scientific principles to enhance API documentation

As technical writers, we are like surfers trying to catch developers’ waves. We can’t control the waves, but we can understand their rhythms and adapt our strategy to ride them successfully. That’s where scientific principles come into play. Just like the knowledge of wave patterns enhances a surfer’s performance, understanding the principles of pattern recognition and learning styles can transform our approach to API documentation.

We can achieve this by:

• Providing comprehensive code examples, catering to opportunistic learners who prefer hands-on exploration.
• Offering layered and in-depth background knowledge, supporting systematic learners who seek a deeper understanding of the underlying concepts.

Furthermore, features that suit all learning styles and facilitate an understanding of the API are beneficial for everyone. 

In conclusion, effective API documentation isn’t just about providing accurate information, it’s about making exploration enjoyable and the learning process intuitive. With great API documentation, developers won’t just learn how to use our APIs, they’ll also enjoy the learning experience.

Writerside lets you mix manual API descriptions with auto-generated references to cater to the needs of any developer persona. You can choose to generate the entire API reference or select specific tags or operations. You can also generate separate pages for API objects or include them on the same pages as the operations to provide all the information in one place.

While there may not be specific literature on applying these principles directly to API documentation, many resources tackle elements of learning theory, instructional design, and behavioral theory that can be adapted for technical writing. We’ve highlighted some of them in the resource section below. 

Feel free to don your lab coat and conduct some research yourself! Although it may not always be feasible to replicate the extensive studies mentioned earlier, there are simpler methods that can still provide valuable insights.

Consider techniques like:

• Content analysis with color coding: Highlight different knowledge types within your documentation to assess their distribution and identify potential gaps or imbalances. We at Writerside are considering delegating this task to AI. If that sounds interesting to you, please upvote this ticket.
• Observational studies: Ask a fellow developer to approach your API documentation as a new user, starting from the API portal. Observe their navigation patterns, information-seeking behavior, and any points of friction they encounter.
• Heatmap analysis: If your analytics system provides heatmaps, analyze user interactions on your API documentation pages to understand which sections receive the most attention, what the happy path is, and which areas might be overlooked.

These insights can provide a roadmap for improving your API documentation, leading to a smoother and more enjoyable developer experience.

Remember, there are no rigid guidelines or definitive solutions in technical writing. However, if there were one golden rule, it’d be this: Write with your users in mind, especially now that you know how their minds work. So, keep experimenting and learning, and most importantly, enjoy the writing process!

Give your API docs their rightful place with Writerside! Learn more.

Resources for further exploration:

• Patterns of Knowledge in API Reference Documentation by Walid Maalej and Martin P. Robillard: https://www.cs.mcgill.ca/~martin/papers/tse2013a.pdf. 
• How Developers Use API Documentation: An Observation Study by Michael Meng, Stephanie Steinhardt, and Andreas Schubert: https://sigdoc.acm.org/wp-content/uploads/2019/01/CDQ18002_Meng_Steinhardt_Schubert.pdf. 
• Learning Science for Instructional Designers: From Cognition to Application by Clark N. Quinn.
• Design for How People Learn by Julie Dirksen.
• Make It Stick: The Science of Successful Learning by Peter C. Brown, Henry L. Roediger III, and Mark A. McDaniel.