This article is based on my PhD research which focuses on video games, and highlights the experience I gained as a digital content writer. During our research at Pronovix, I had several ‘aha!’ moments. I hope you will have the same experience while reading, and the article will shed new light on UX and DX.
Video games usually have two main components: the gameplay and the story. The gameplay means the challenges given by the system, the control options, while the story gives a background, a cause and effect explanation for the fictional world’s happenings. This article will focus on the former and the similarities with developer portals.
As far as I see, in the case of developer portals and video games, the key to success is a positive experience. If someone can immerse themselves in the world of codes or fiction, the given framework is sufficient for their expectations. Or challenging and rewarding enough to maintain their interest.
As Robert Zubek underlines in his book, the ‘user-centered design is fundamental to game design. A game is designed as an experience, an interaction that gives the player agency and autonomy.’ (p. 3.)
We also pointed out in a previous article that developer experience (DX) ‘is user experience targeted to a technically savvy audience.’ When someone accesses a developer portal—not only people with a technical-focused mindset—they expect the content and information to be easily digestible, reliable and up-to-date.
As I see, both in successful video games and developer portals the user experience is carefully designed.
In devportals, good information architecture is crucial, and the lack of it can lead to difficulties. For example:
- if the entry point to accessing an API is unclear or
- there are obstacles to accessing an API quickly or
- users need the API provider’s help every time they have a question/issue,
such lapse can evoke frustration and can decrease the trust towards the developer portal, its APIs and ultimately the brand.
Frictionless game design is also essential, bugs and lags can ruin the whole experience. For example:
- if a gamer’s actions do not create feedback loops or
- not the expected feedback happens or
- the game does not deliver what was promised (e.g. the visual design is not as high resolution as it was shown in the trailer)
then there is a high chance that the game will cause frustration, decrease the trust towards the publishers and be forgotten quickly.
That said, there are several differences between video games and devportals. This sounds obvious, but if we deep dive into the similarities, it is worth looking at the differences. The two media have diverse:
- user goals,
- audiovisual approaches,
and the success metrics can vary as well. It can be fruitful to analyze the parallels further. How can the user experience be designed?
User Experience in Video Games
The game journey is enriched with obstacles to make the gameplay more interesting and challenging. The player enters a fictional world that we can call—following Johan Huizinga’s term—a ‘magic circle’. This ‘circle’ is separate from our everyday life both spatially and temporally (the game has duration and a framework). In other words, new rules apply.
If the gamer is willing to spend more time in the game, there is a high chance that the user experience is satisfying. As Janet H. Murray stated, we can use the term immersion, because gamers immerse themselves in the fictional world the same way when we are submerged in water: ‘the sensation of being surrounded by a completely other reality, as different as water is from air, that takes over all of our attention, our whole perceptual apparatus’. (p. 99)
We usually play a game because experiencing the flow from focus and stimuli creates a pleasant feeling. Game developers want us to spend as much time with their game as possible and be a part of this small, distinct game world. A carefully designed user experience increases the chance of success.
When a game is too challenging, there is a chance that the gamer will be overly frustrated. However, when they can solve a hard task, there is a rewarding satisfaction: relying on logic and determination, they achieved something. But what about developer portals and this type of challenge?
Developer Experience of Devportals
Developers are invested in using developer portals both as API providers and as API consumers. In their process of working with APIs, people don't want to encounter monsters and challenges. They enter the "circle" on their "quest": they open to and navigate on the devportal because they want to complete a task. Quality and time are usually crucial factors: developers need to accomplish their work effectively and quickly.
As we mentioned in a previous article, ‘in some cases your API might only have a few minutes to hook a developer, if it isn’t immediately clear where developers can start their integration efforts, they might leave and never come back.’ Insufficient architecture can damage the developer experience.
Certainly, developer portals usually have several types of user personas (e.g. business personas, techwriters, DevRels and so on). Video games also have several users (personas) who have different backgrounds. For that reason, many games offer different casts of characters which can make the gameplay diverse, and for that reason, every narrative is unique (e.g. the in-game archer has different tasks/route from spell casters). The goal is always the same: communicate clearly, use trust signals, be consistent and up-to-date, provide easy-to-follow guides.
As Marco Spinello (senior technical writer at Miro) as guest at the API the Docs podcast so succinctly put, 'We are writing documentation. We are writing something that is a tool. It’s not a work of art. It is not something that is for its own sake. It needs to serve a purpose, needs to get people out of trouble, basically in as little time as possible.'
Design and curate the experience for each of the portal's user personas, to increase their chance of success on their current quest. In other words, developer success is different from gamer success.
Start your journey: Tutorials
How do players and developers know what they can do? There are several onboarding options, but now I would like to focus on tutorials.
Just like developer portals, video games also have tutorials that clearly explain the functionalities and the possibilities. Maybe you are familiar with the feeling when a tutorial has started and you just pressed the “Skip” button. I find it interesting that many video games don’t require explanations anymore, because the control options (e.g. press the spacebar if you want to jump) are well-known to the gaming community, we can say that there is some uniformity (of course, there are exceptions).
As Lindsay Grace highlights, as a game designer, you want to ‘give a player an enjoyable experience, you may want to skip what they already know and move right to what they don’t. So, for example, if the player is already comfortable with the rule set or actions of the game, you don’t want to bore them with a tutorial explaining what they already understand.’ (p. 65) To avoid frustration, ‘you need some way of assessing their current skills. This is likely some basic form of assessing the player’s ability and understanding of the game rules.’ (p. 65-66)
When explanation is necessary (e.g. how to combine different skills), the best approach is to make it short, to the point, and it shouldn’t pause the gameplay. If the user is already familiar with the controlling options, but they can’t skip the tutorial and it stops the game’s flow, it is highly possible that they will be frustrated. On the other hand, if a user is new to the gameworld and the control options are unique, the lack of explanation can also damage trust.
In the case of developer portals, tutorials provide step-by-step explanations that get API consumers to experience the product as fast as possible. Even though we have been working with APIs for years, we still need an explanation (and sometimes help) specific to the API. There are some kinds of standards on how to use the APIs, but in many cases, tutorials are welcome and needed. But the onboarding process should be seamless and easily understandable to every audience.
Both video games and developer portals have some standard elements, patterns which are easily recognizable to its audience. But some kind of support is always welcome: in the case of developer portals, besides tutorials, FAQs, forums, and guides are also common.
If someone is stuck in a video game (e.g. they don’t know how to solve a problem/quest), they can also search for a solution on different forums (such as YouTube). A game’s playthrough can explain and show every step for the solution. Just like the developer, the gamer community members also help each other with their findings and experience. There are also several game Wikies where players can deep-dive into the game mechanics and learn more about the lore (which is not the main storyline, but it builds the gameworld’s story further).
We can learn from video games that user-centered design is essential, and tutorials should be clear for a diverse audience. Users are not on the same level - not every gamer is familiar with controllers such as not every developer has the same knowledge about coding - but too much and too detailed explanations could be frustrating.
Developers come with a given problem to the site and they don’t want to waste much time searching for answers. Players also dislike when a game doesn’t allow them to go on their own route, and has to face too many explanations.
In contrast, time spent on a developer portal and with a video game varies. Gamers want to immerse themselves in a fictional world and wait for challenges. Developers don’t want to encounter obstacles.
Next article: Loading…
All Pronovix publications are the fruit of a team effort, enabled by the research and collective knowledge of the entire Pronovix team. Our ideas and experiences are greatly shaped by our clients and the communities we participate in.
- Zubek, Robert: Elements of Game Design. Cambridge, Massachusetts, London, England: The MIT Press, 2020.
- Murray, J. H.: Hamlet on the Holodeck. The Future of Narrative in Cyberspace. New York, NY: The Free Press, 2016.
- Huizinga, Johan: Homo Ludens. Study of the Play-Element in Culture. London, Boston, Henley: Routledge & Kegan Paul, 1949.
- Grace, Lindsay: Doing Things with Games. Social Impact through Play. Boca Raton, London, New York: CRC Press, Taylor & Francis Group, 2020.
- Grow and Help Grow: Developer Portal Services
- Building Developer Portals Step-by-Step: Information Architecture Workshops
- Developer success: looking beyond developer experience
- How do developers learn about APIs?
- Onboarding Pages
- Techwriting, DX and DevRel Working Together at Miro - Part 1
Klaudia is a Digital Content Writer and Editor for Pronovix' Marketing and Content Strategy Team. She conducts research into developer portals and developer experience and writes articles on products, services, and events. She also works on case studies. In addition. she edits the podcast episodes. Klaudia is also working towards a PhD in literary studies focused on video games. In her free time, she practices photography and reads.