This talk was presented at API The Docs Virtual 2022 event series on 26 October. We are glad to present the video recording, slide deck and talk summary below. Enjoy!
Visit the talk listing page for an overview of all presentations!
Emese Hallgató
Psychologist, UX Researcher at Pronovix
Emese's presentation (video recording)
Emese's slides
Q&A
- Can we catch the moment when we switch from one state to the flow?
- When there is an already existing documentation artifact, how can we check if something is contributing to control or arousal or it is a distraction? How do we know that?
- What are your views on having more conceptual topics like Overview topics and the impact on the flow?
- Is there a way that we know of to bring someone from the state of frustration to the state of safety?
- Is providing flow state equally important for all 3 development approaches you described?
If you are interested in the topic, you can listen to the API The Docs podcast episode, where Emese was the guest or you can read her article.
Happy path for developers
Happy path: a user experience in which developers get what they need. Their journey is simple, fulfilling and seamless. A good design is invisible, but the lack of it can lead to difficulties and frustration.
If we want to give developers the happy path, we need to understand:
- their goals,
- why do they come to the devportal,
- what information do they need,
- what content do they expect to find.
Each developer portal has its own audience. The audience has unique needs and challenges, but there are some general principles that can be applied when designing for them. Steven Clarke (2007) observed that there are three approaches to software development. Recent scientific researches have validated Clarke’s theory.
3 approaches to software development
Systematic approach: the developer prepares in advance, educates themselves. Their process of API learning is:
- review concepts and architecture documentation,
- take time to prepare the development environment,
- form hypotheses about possible approaches,
- follow the proposed processes.
Their journey: learn and understand the architecture and the design, and they start to code when they feel they have the knowledge.
Opportunistic approach: they will learn by doing their work, they are like explorers. Their process of API learning is:
- quickly scan through the documentation, start experimenting,
- reuse code examples/other people’s solutions,
- make several web searches, they have a lot of open browser tabs.
Their journey: they spend less time initially on the devportal, start to code (do an alternating pattern of coding and information gathering). They frequently come back for information, but not necessarily to the devportal, they use other sources as well.
Pragmatic approach: a combination of the previous two approaches. Their process of API learning is:
- learn enough to start (more than the opportunistic developer but not as systematically as the systematic developer does), then refer back to the documentation (or other sources) as needed.
Their journey: it is in between the systematic and pragmatic approaches.
Why is it important?
Even if we provide every type of content that they might need, it might not be enough. Conceptual information is helpful for developers to have. The opportunistic approach does not consume these guides as they want to understand by doing not by learning.
If we place this information in code examples, then they will find it, as every type of approach utilizes code examples.
State of flow
Flow: originates from Mihály Csíkszentmihályi and the term refers to the optimal feeling, when we are immersed in an activity. In this state the performance can be up to five times more than how it is in general.
“In this state, which is called flow, the inner critic is silent and you can get all the ideas that your mind is capable to give you.”
Questions to ask to make the developers happy
- What type of information do developers need?
- What kind of mindset do they come to a devportal with?
- How to maximize the chance that developers will experience flow?
There are some common triggers that can help developers to reach the state of flow. They need to actively concentrate on an activity, and the challenge to skill ratio has an important role in this. When the challenge is high, but they have the necessary skills and they can manage the challenge, flow occurs.
Some triggers/correlates to flow:
- intensely focused attention,
- clear goals,
- immediate feedback,
- risk,
- rich environment.
How can we use this knowledge to help developers?
- Improve their skills with teaching materials, tutorials, guides (make it interactive, mentally consumable and set expectations in advance).
- Increase the challenge with social activities, for example with competitions, cooperations.
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.
