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.

USER SKILL ACQUISITION STAGE
PROFILE
DOWNSTREAM DEV JOURNEY STAGE FOCUS
THINK ABOUT...
(API DOCUMENTATION & DX ELEMENTS)
User: Novice developer
Profile: “Tell me exactly what I need to do to make this work”
Focus: the get started stage in the downstream developer journey
Easy onboarding process with clear steps
Step-by-step tutorials
Getting started guides
SDKs as onboarding tool
Programming language selector
User: Advanced beginner developer
Profile: “Let me try this out…”
Focus: the evaluate stage in the downstream developer journey
Landing page scope & structure
Blog articles (reading)
Try-out options, demos, samples
Step-by-step use cases
Worked examples
Conceptual documentation about API architecture (visuals)
Code examples
How-to guides
3-column reference page with programming language selector





User: Competent developer
Profile: “How can I solve this?”
Focus: the discover & research, develop & troubleshoot stages
in the downstream developer journey
Landing page scope & structure
Blog articles (reading)
Trust signals
Use cases
Worked examples
Legal documentation (not too detailed)
SDKs
Glossary
Concepts about API architecture (visuals)
Topic guides
How-to guides
Code examples
Contact form
FAQ
References







User: Proficient developer
Profile: “I know how this should work, I just need to figure out the best way to do it”
Focus: the discover & research, develop & troubleshoot stages
in the downstream developer journey
Landing page scope & structure
Blog articles (reading)
Trust signals
Use cases
Worked examples
Legal documentation (detailed)
Glossary
Concepts about API architecture
SDKs
Topic guides
How-to guides
Code examples
Feedback options
Contact form
FAQ
References
Discussion forum
Community page



User: Expert developer
Profile: “Here, I’ll show you…” & “I just know”
Focus: the celebrate and maintain stages in the downstream developer journey
Blog article writing
Use case writing
Legal documentation (detailed)
SDK writing
Guide writing
Feedback options
Discussion forum
References (comments)
Community page

Resources



Thanks to Laura Vass for editing this article!

About the author

Kathleen De Roo

Information Architect, Technical Content Writer

Kathleen started as a technical content writer, responsible for doing research and writing on developer portal aspects. As an information architect, she helps clients find out how to align business goals and user needs with the knowledge we gathered about devportals.

She holds master's degrees in history and in archival science & records management.