Mapping Software Developer Journeys To Deliver Relevant Content

A 2023 study, "Mapping the Information Journey: Unveiling the Documentation Experience of Software Developers in China," examines the behaviors, characteristics, and preferences of Chinese developers.

Using interviews and surveys to understand developers' information journeys and expectations for quality documentation, researchers reveal differences in documentation use between junior and senior developers, identifying four main stages of their information journey:

• Exploration

• Understanding

• Practice

• Application

The researchers make several specific recommendations for organizing software documentation (like API Docs) based on these stages, adapting to different developer levels, and prioritizing content organization and maintenance to enhance the developer experience.

Here's a summary of their recommendations:

1. Organize documentation based on the developers’ information journey:
   
   Documentation should be structured to align with the distinct stages of the developers’ information journey: Exploration, Understanding, Practice, and Application. Each stage has different needs, from conceptual information and experience sharing to code examples and technical details. A well-structured documentation that aligns with these stages can significantly enhance efficiency and effectiveness.
   

2. Adapt Documentation to Different Learning Needs:
   
   Recognizing that junior and senior developers have varying habits and preferences, documentation should offer diverse learning aids, such as video tutorials for beginners and comprehensive, in-depth examples for more experienced developers. This approach helps in catering to the wide spectrum of developer experience levels.
   

3. Prioritize Basic Experience Dimensions in Documentation Design:
   
   Software developers say that for documentation to be of use to them it must be correct, clear, complete, and regularly updated. Moreover, incorporating interactive design elements like online code editors can significantly enhance the developer experience by facilitating immediate practice and application.
   

4. Integrate Marketing and Technical Communication:
   
   Software documentation serves as a vital link between technical and marketing communication. Effective SEO and integrating documentation with an online community make it easier for developers to quickly find solutions and share knowledge with others.

Other studies highlight the barriers that incomplete or incomprehensible documentation creates, leading developers to seek information from external sources like StackOverflow and blogs rather than official API documentation.

Researchers note that some software developers prioritize solving challenges and often avoid seeking a deeper understanding of the underlying software or API, which aligns with the notion that developers aim to efficiently resolve tasks without mastering the finer details. These findings shine a light on the importance of providing clear, concise, and task-oriented documentation to meet developers' needs effectively.

See also: What software developers want from API documentation and read the research this post summarizes.