When do Software Developers Use Guides?

When and how do software developers use guides in their API integration journey, and what are their preferences regarding them? This article aims to address these questions by drawing insights from user interviews conducted by the Pronovix UX Researcher Team. We aim to equip you with insights to enhance your developer portal, whether by incorporating user-centered design to already planned content, or by strategically choosing the most effective guide type to improve the API integration experience.

In the article, we will use direct quotes from the developers sourced from our interviews. All quotes are anonymized to respect the participants’ privacy.

PRIORITIZING EFFICIENCY: HOW GUIDES ACCELERATE DEVELOPERS’ PROBLEM-SOLVING

Developer portals play a pivotal role in providing comprehensive documentation and resources for integrating APIs. Research shows that incomprehensible, incomplete, and outdated documentation is amongst the most common problems developers face [1]. Software developers arrive at documentation portals with specific problems at hand to solve, they do not want to waste time trying to have a thorough understanding of all that a certain API can do. Find a solution to a specific problem as soon as possible without confusion. Alas, software comprehension remains time-consuming.

Discover how to foster collaboration and innovation in your developer portal by understanding consumer-side needs, production-side contributors, and essential documentation types. 

 

 

Read more »

According to our results, when developers have a specific task to solve, they seek a solution in the technical documentation. The majority of the developers interviewed in this user research preferred to find all information regarding the setup process in the technical documentation, and if that satisfied their needs, they went straight to trying out or implementing the API afterwards.

'Usually, it's not really necessary to have tutorials if the documentation is well done, well written. In my opinion, the documentation should be a tutorial itself.' - Bob

Developers find it hard to understand purely technical documentation if they don't have the expertise to grasp it or if the docs lack in-depth explanations. In such cases–when the technical-only documentation is not enough–, guides serve as an invaluable resource for providing specific, step-by-step instructions that help navigate developers towards a solution.

'Sometimes I have a small, very to-the-point example right on the front page of an API and I can get an initial idea of how quickly I can get on board. Some APIs have a more complicated process and point to a get started page where there are a lot of prerequisites. [...] Perhaps then I'll need to look into a tutorial or to analyze the documentation more thoroughly.' - Jane

EXPLORING DEVELOPERS’ PREFERENCES FOR CERTAIN TYPES OF GUIDES

Tailoring the documentation to the specific needs of the portal’s users ensures that they can easily find the information they need for successful integration and development. Naturally, the choice of guide types often depends on developers’ individual learning preferences, for example, hands-on experimentation with an API might prove to be more effective for some developers than simply reading about it. Also, developers might skip certain sections and head straight to the most relevant part of the guide depending on their skills and preferences.

In the upcoming sections, we will reflect on the different types of guides from the users’ standpoint. The interconnection among these types depends on the actual content and content strategy, but in this article, we are describing them progressing from the comprehensive to more targeted, task-oriented guides:

• Guides
  • Tutorials
  • Use cases
  • Step-by-step guides
  • Recipes
  • Codelabs

Tutorials

Among the various forms of guides, tutorials stand out as the most widely used, as they can be helpful in several situations:

1. When the documentation lacks clarity
2. When the documentation is outdated
3. When a quick start is desired
4. When complex operations demand multiple prerequisite steps

'Sometimes tutorials are more to the point than the actual documentation for certain APIs, because they show you how to use various endpoints together and reach a certain productive capability, rather than having to piece together every component from the documentation pages.' - Emma

Use cases

Use case documentation is a great way to break down complicated problems into step-by-step actions. It describes what a developer needs to do exactly to achieve a specific goal. Use cases tell users how to obtain that end result and often address a technical audience that wants to evaluate and understand a specific problem or solution. Developers can compare use cases to their personal needs, and use cases facilitate their understanding by providing comprehensible and manageable steps. For example, if an endpoint is not straightforward, use cases create a story behind what it’s supposed to do.

Step-by-step guides

Ideally, when developers read tutorials, they expect a step-by-step explanation for their specific operation system and machine. They seek not only the ‘how’ but also the ‘why’ behind each action. These guides can serve as a quick-start, simplifying the environment setup and showcasing the essential steps to setup an API, such as calling a single endpoint. It is important that the information is well-organized and is “split into smaller chunks”, so that it is easier to follow instructions like “use this endpoint to do X and then use this second endpoint to do Y, and use this third endpoint to do Z”.

Additionally, the guide’s intended objective needs to be taken into account. If developers seek help for specific problems, they might need more in-depth help than just the tutorials, like a step-by-step guide, a how-to or a use case. For example, as Abbie highlighted: 'use cases would be higher than tutorials, because tutorials are simpler sometimes, they are more abstract and less specific.'

Recipes

In software development, a “recipe” refers to a set of instructions or guidelines that developers can follow when aiming to accomplish a specific task or implement a certain functionality using an API. Positioned between tutorials and use cases, recipes provide a step-by-step approach with code examples, offering insights into the implementation of features, solutions to common problems, and the integration of the API.

Comprising sample code snippets, configuration setting and explanations of the expected outcomes, recipes serve as technical guides tailored to specific use cases. If recipes can be understood easily by developers, they can facilitate the integration process, reduce development time and offer practical, hands-on guidance to developers.

While these types of guides are widely appreciated by developers, it’s essential to note their technical nature. In recipes, the focus is more on showcasing lines of code and elucidating the necessary steps, and less on extensive written explanation about how to use them.

Developers highlighted that understanding such documentation might pose a challenge for people with limited experience in software development.

Interactive tutorials (“walkthroughs”)

Interactive tutorials where the user can perform exercises facilitate the learning of intricate processes. In such cases, the user must perform the steps that are needed to achieve the desired outcome, so they can learn by doing instead of relying solely on textual explanations. Besides the hands-on experience of performing these steps, features for testing the knowledge after each section help the user to remember them.

VISUAL AIDS IN DOCUMENTATION: BALANCING UNDERSTANDING AND EFFICIENCY

Developers often find explanatory videos and images to be invaluable resources. They help to understand intricate concepts, provided these visual elements are well-crafted. As a developer stated:

'With images, it’s easier to understand, because you need to imagine very often what [the functions] will be in the future.' - Dave

This sentiment is shared by many in developer communities, for example:

'I don't like just reading about [how to work with the API], I like to see it done generally.' - Sarah

Thus, videos and images play a crucial role in helping developers understand the outcome from solutions, yet it’s essential to keep in mind both advantages and disadvantages. Videos, for instance, can save time when they effectively showcase a process, making it easier for developers to grasp a concept. However, if videos are too lengthy and overly explanatory, they risk being overlooked by developers. Videos ideally should be short clips, or shouldn’t exceed the 30-60-minute mark.

To make extensive textual documentation or lengthy videos less repellent, you could offer a brief summary or a demo at the outset of the content. This allows developers to quickly assess whether they need to delve into the full video or documentation. It empowers them to make an informed decision without the commitment of watching an entire video or reading a lengthy document, thus saving time and minimizing frustration. Reading lengthy documentations is often a pain point for the user, it doesn’t mean that we should omit them. As artificial intelligence (AI) is on the rise, we can expect it will transform documentation consumption as well. In our study, some developers highlighted that they are already using AI for writing code, testing APIs, finding bugs, and even for finding information they need:

'Having to read some pages of the documentation is very boring for me, but with the new technology, for example ChatGPT, this is not a problem, because you can ask it to provide for example a particular function you need, and it gives you an example of a script with that function. This is a good thing for me.' - Casey

Another thing to keep in mind regarding audiovisual content is that it is more difficult to search within audio-video than in written content. Users who would like to search for specific information can’t just search for keywords the way they are used to do so in written content. Also, the maintenance of a video might involve much more effort, as they get outdated quickly by any changes in the subject illustrated. Videos might be a good option to explain concepts or processes with context (and they are, if they are done well), but remember to consider the long-term cost of maintaining them.

People value images for their ability to easily share a mental model, but make sure that key information isn't sacrificed in the modeling process. Remember that images may simplify concepts towards a certain perspective, potentially leading to a loss of information (false negatives or positives). Striking the right balance between clarity and completeness is crucial when incorporating images into documentation.

ACCESSIBLE CONTENT AND VISUAL AIDS

When strategizing the use of images and videos on developer portals, consider inclusivity and accessibility. Features like alt text, captions, and transcripts enable screen readers to describe the content, ensuring that everyone, regardless of abilities, can engage with it.

Code and design developer portals to adhere to accessibility standards. Make sure that the content is understandable by all of the users. Inclusive content is generally useful for all, but is essential for people with disabilities. Ultimately, ensuring that the content, images and videos on developer portals meet accessibility standards goes beyond legal compliance: it fosters inclusivity, improves the user experience and demonstrates ethical digital practices.

The most well-known disability that affects vision is blindness. For users who are not able to read the content or see the images, alt-text can help understanding by describing the content of an image. However, according to studies, 70% of computer users have health problems that affect their vision in some way and features like changing the contrast or font size are essential for reading.

The most common computer-related problems are musculoskeletal problems. Extensive computer use and mouse misuse among software developers lead to musculoskeletal injuries like repetitive strain injury or carpal tunnel syndrome, which limits the ability of using pointer devices [2]. Of course, ergonomic devices exist to prevent these injuries, but given the high chance of them, consider providing and streamlining alternative navigation options on developer portals as well.

Besides disabilities and temporary limitations, situational limitations like a noisy background might mean that the user needs to turn on transcription while watching a video.

We highly recommend that you not only consider the sensory accessibility of your developer portal, but also that of cognitive accessibility.

Summary

Diverse guide formats make it easier to use APIs and effectively complement the very information-dense technical documentation – if they directly accommodate the various user needs. When establishing or improving a developer portal, it’s essential to tailor the content and features to your audience’s skill levels and capabilities.

If you would prefer Pronovix to assist you in achieving this, we propose our UX services:

• We collaborate with you to discover your business requirements and clarify the expectations of your users.
• Our team aids in comprehending the users’ journeys, pinpointing areas of friction, and identifying opportunities for improvement.
• We deliver a personalized UX package designed to elevate your portal, ensuring a seamless and engaging user experience.

Resources and useful readings:

• [1] Meng, M., Steinhardt, S., & Schubert, A. (2019). How developers use API documentation: an observation study. Communication Design Quarterly Review, 7(2), 40-49.
• [2] Shrivastava SR, Bobhate PS. Computer related health problems among software professionals in Mumbai: A cross-sectional study. Int J Health Allied Sci 2012;1:74-8
• Meng, M., Steinhardt, S. M., & Schubert, A. (2020, October). Optimizing API Documentation: Some Guidelines and Effects. In Proceedings of the 38th ACM International Conference on Design of Communication
• Cognitive accessibility for developer portals: accessible content for every user by Klaudia Jancsovics
• How do developers learn about APIs? by Emese Hallgató
• What do developers do when it comes to understanding and using APIs? by Emese Hallgató

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.