User-focused Content Design for API Documentation

Learning journeys along the downstream developer journey

In previous posts we have been researching how developers who use a public API move on a specific developer portal. We looked at how their background (skills, interests, approaches, previous experience with the specific portal and its API products) and tasks at hand can define at which stage of the downstream developer journey they enter first.

At APIdays Paris 2018, Ronnie Mitra gave an insightful talk on how to improve API documentation and learning experiences, for which he gathered inspiration from the Dreyfus model of skill acquisition.

In this post, we’ll dive a little deeper into the whole topic and illustrate Ronnie’s conclusions by giving an overview of content and DX elements we imagine would help developers along their learning journey.

Main concepts of the Dreyfus model of skill acquisition and of Ronnie Mitra’s talk “How we learn”

The Dreyfus model of skill acquisition focuses on how learners evolve while widening their skill set within a specific framework: it implies linear (personal learning) development from skill set A to skill set Z. Accordingly, the order of the Dreyfus model stages does not necessarily correspond with the way we, at Pronovix, use to order the developer journey stages (for more information check the overview table below).

The model focuses on 5 types of learners (novice, advanced beginner, competent, proficient, expert). Ronnie Mitra gives tips on how we could target them, as developers that is. He also points out that although the model’s not perfect, it can help us to take the needs of API users at different learning stages into account when you plan and develop content.

The five stages of directed skill acquisition

Stage 1 — Novice: “Tell me exactly what I need to do to make this work”

Novices are at the beginning of their learning journey. The instructor (this could be a colleague or a virtual tool) makes sure that they can follow context-free rules and recipes, but also start to understand the context to be able to perform well and evolve into advanced beginners.

How can you target the novice developer?

• Provide clear, rule based direction,
• No need to explain how or why, just help learners get started,
• Simple, clear and highly prescriptive content,
• Examples (recipes) should match real-world, solvable goals.

Stage 2 — Advanced beginner: “Let me try this out…”

These learners already gained some practical experience, so rules can become more complicated. Advanced beginners learn to recognize new aspects, especially after having seen a sufficient number of exercises: progression comes from practical experience, the learners recognize (also context-free) situations. Instructions and examples are still important though.

How can you target the advanced beginner developer?

• Make it easy to find basic information for continued practice,
• Provide an environment to make practice cheap and easy,
• Don’t re-introduce novice level information,
• Avoid noise from too much contextual information (special conditions, performance implications, dependencies, etc..).

Stage 3 — Competence: “How can I solve this?”

Competent users are able to pick the rules and recipes that they need in a specific situation. This stage can be frustrating and exhausting, as the learners start to see the bigger picture: the number of relevant elements that they are able to recognize can become overwhelming.

How can you target the competent developer?

• Tutorials should be less prescriptive, but still rule and recipe based,
• Content can be geared towards problem-solving and higher user engagement – you don’t need to outline every step,
• Help developers understand when particular types of usage makes sense,
• Content that challenges the developer may be useful.

Stage 4 — Proficiency: “I know how this should work, I just need to figure out the best way to do it”

To reach this stage, you have to leave the safety of rules: personal and situational experience becomes more important. The user is involved and invests to gain further skills and can feel what needs to be done but not what to do to achieve this, at least not automatically or intuitively — for that they deliberate and calculate.

How can you target the proficient developer?

• Visibility of previous calls is important so that developers can self-improve,
• Complex sample applications, use cases and community stories should be available,
• Content should be less-prescriptive and more contextual (Example: “API clients must be capable of handling changes to the interface”),
• Content that is targeted at novice and advanced beginners will frustrate a proficient user.

Stage 5 — Expertise: “Here, I’ll show you…” and “I just know”

Expert users immediately see how to achieve goals (subtly and refined) — they are able to act by instinct and intuition.

How can you target the expert developer?

• Provide avenues for experts to share their knowledge:
• With you,
• With other learners,
• With prospective users.

What API documentation components and DX elements do you need?

What content helps developers at a specific learning stage? What DX elements can help them do their job well? In the following table you can find possible solutions.
Interested in what could come first and what second when you plan content? Read our article on the MVP for a developer portal.

Resources

• Ronnie Mitra, How we learn, 2018,
• Stuart E. Dreyfus, The Five-Stage Model of Adult Skill Acquisition, 2004.

Thanks to Laura Vass for editing this article!