Using the Dreyfus model of skill acquisition to improve API documentation and learning experiences. Delivered at API Days Paris 2018.

1. How We Learn
Lessons from the Dreyfus Model of Skill
Acquisition
Ronnie Mitra
Lead Designer
API Academy
@mitraman
ronnie.mitra@ca.com

2. The Intuitive API:
No documentation Needed
“Give me the balance data for this customer’s
bank account”
….does not exist today

4. Bill Verplank

5. How do we guide learning and reduce the
number of interactions required?

6. Hubert and Stuart Dreyfus
• Co-authored “Mind Over Machine” in 1986
• Developed a five stage model of directed skill
acquisition
• First published in 1980
• Re-published in Mind over Machine
• Updated in 2004
• “The Dreyfus Model of Skill Acquisition”
Hubert Dreyfus
Stuart Dreyfus

7. Five Stages of Directed Skill Acquisition

8. “Tell me exactly what I need to do to
make this work”
Stage One: Novice

9. Stage One: Novice
• Beginning of the learning journey
• Context-free rules and recipes
• Highly directed learning

10. Stage One: Novice
In the game of chess:
• Learn the pieces
• Learn how they move
• Learn a simple strategy: “always control the centre”
In driving:
• Learn the rules of the road
• Learn how to use the pedals, controls and steering wheel
• Shift gears at specific speeds

11. Novices are limited in what they can
accomplish
Stage One: Novice

12. Stage Two: Advanced Beginner
“Let me try this out…”
“Let me try this out…”

13. Stage Two: Advanced Beginner
• Progression comes from practical experience
• Rules become more complicated – can be combination of situations
as well as context free
• Still rule-based – no holistic or “big picture” understanding

14. Stage Two: Advanced Beginner
• In The Game of Chess:
• The player learns to recognize weak positions and how to avoid them
• In Driving:
• The driver uses engine sounds (situational) as well as RPMs to decide when to
shift
• In Golf:
• Use a different technique depending on the lie of the ball

15. Stage Two: Advanced Beginner
“Let me try this out…”
Beginners can’t see the “big picture”

16. Stage Three: Competence
“How can I solve this?”

17. Stage Three: Competence
• Learner begins taking responsibility and seeing bigger picture – not
just the fault of the rules and recipes
• Picking the rules and recipes to follow based on the situation
• Practice leads to exposure to whole situations – start going beyond
the safety of the rules

18. Stage Three: Competence
• In Driving:
• Selective focus based on situation (example: speed vs shifting when exiting
motorway)
• Evaluating many situational conditions and reacting analytically

19. Stage Three: Competence
Competency can be exhausting and
frustrating

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

21. Stage Four: Proficiency
• Higher level of personal engagement and investment
• Proficiency comes from gradual replacement of rules with personal,
situational experience
• Can feel what needs to be done (but not how to achieve it)
• Deliberation and calculation (not intuition) used to achieve desired
goal

22. Stage Four: Proficiency
• In Driving
• The driver intuitively knows she is travelling too fast but has to think about
the best way to reduce her speed

23. Proficiency stops short of “natural” skill
Stage Four: Proficiency

24. Stage Five: Expertise
“Here, I’ll show you…”
“I just know.”

25. Stage Five: Expertise
• Sees what needs to be done and also how to do it
• Playing completely by instinct and intuition

26. Stage Five: Expertise
• In Chess:
• A grand master who plays by instinct
• Can win a match even when analytical part of the brain is distracted
• In Golf:
• A golfer intuitively knows how to co-ordinate their body to hit a shot based on
the lie of the ball and weather conditions

27. The Five Dreyfus Stages
Source: The Five-Stage Model of Adult Skill Acquisition, Stuart
E. Dreyfus

28. The Five Dreyfus Stages
Source: The Five-Stage Model of Adult Skill Acquisition, Stuart
E. Dreyfus

29. The Five Dreyfus Stages
Source: The Five-Stage Model of Adult Skill Acquisition, Stuart
E. Dreyfus

30. The Five Dreyfus Stages
Source: The Five-Stage Model of Adult Skill Acquisition, Stuart
E. Dreyfus

31. The Five Dreyfus Stages
Source: The Five-Stage Model of Adult Skill Acquisition, Stuart
E. Dreyfus

33. API UX: Design for User Platform

34. API UX: Design for Dreyfus Stage

35. Targeting API Novices
• 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

36. Targeting API Advanced Beginners
• Make it easy to find basic information for continued practice
• Example: in a CRUD API, make resources easily findable along with their
operations (reference)
• 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..)

37. Targeting API Competence
• Tutorials should be less prescriptive, but still rule and recipe based
• Content can be geared towards problem-solving and higher user
engagement – 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

38. Targeting API Proficiency
• 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

39. Targeting API Expertise
• Provide avenues for experts to share their knowledge
• With you
• With other learners
• With prospective users

40. Do You Want To Have Expert Users?
• It depends… but, probably, yes!
• Experts can develop applications quicker, are more invested in the API
and can foster a community
• Helping a learner progress to expert-level requires a big investment

41. … But Do Your Users Want To Be Experts?
• It depends… but, probably not.
• Your API is usually a means to a different goal – when the job is done,
the learning stops
• API users only invest in mastery if they are motivated :
• Can experience with your API offer long-term employment?
• Is it a platform on which they can build anything of value to them?
• Is their prestige in being acknowledge as an expert of your API?

42. Identify the learners that will help you succeed
…and invest in guiding their skill acquisition

43. Use the Model as a Tool
• Models aren’t perfect
• You don’t need to account for every learning stage
• Consider the needs of learners at different stages when developing
your content

44. Useful Resources
• The Five-Stage Model of Skill Acquisition (2004, Stuart Dretyfus)
http://www.bumc.bu.edu/facdev-medicine/files/2012/03/Dreyfus-
skill-level.pdf
• Mind Over Machines (Dreyfus & Dreyfus)
• Pragmatic Thinking and Learning (Andy Hunt)

45. Applying the Model: Who Was This Talk For?
• Primary Audience: API Documenters
• No specific examples or recipes provided
• I described a model and pattern that could be used

46. Who Is The Target API Documenter For This
Talk?

47. How We Learn
Lessons from the Dreyfus Model of Skill
Acquisition
Ronnie Mitra
Lead Designer
API Academy
@mitraman
ronnie.mitra@ca.com