Exploring Web3 Documentation: Key Challenges and Growth Opportunities for DevRel Teams
Owanate Amachree
The developer experience (DX) space is constantly evolving. It goes beyond merely building developers' tools and products to discover how DX increases business success in Web3.
This series will cover how DevRel teams can focus more on reshaping or crafting exceptional developer experiences, starting with reimagining existing documentation or creating new documentation experiences. We will explore the specifics of understanding the developer audience, crafting effective information architecture patterns, selecting the right documentation platform, and conducting a content audit and inventory for your documents.
Here is what to expect:
Information Architecture and Content Inventory and Planning
Docs Platform development, Content Migration and SEO
Go-to-market strategies for web3 documentation
Let’s get right into it.
One aspect mainly discussed related to DX is providing developers with the tools, community support, and up-to-date resources. This is where documentation plays a significant role. Documentation is vital to the DX funnel (from awareness to product). The AAARRRP is a framework that helps you define your developer relations strategy by providing a mechanism for mapping the company goals for developer relations through to the activities that will help you achieve those goals.
However, fewer platforms do not prioritise documentation because measuring success against business goals is quite a herculean task. The diagram above shows the AAARRRP pyramid from awareness to the product's stage. From developers being aware of the product, signing up for the product, and using the product to activating and retaining devs through providing concise, up-to-date documentation and tailored resources, all these play a significant role at the different stages in the developer funnel.
To better understand the unique challenges and opportunities in Web3, let's compare traditional and Web3 documentation.
Key Differences between Web3 Documentation and Traditional Documentation
Web3 is still in its infancy, and challenges abound with any emerging technology. Many Web3 projects grapple with creating documentation that effectively onboards and guides developers through a platform. A common pitfall is neglecting the developer journey and failing to tailor content to user needs.
This presents a significant opportunity. Since technical documentation remains the top resource for developers learning new technologies (Stackoverflow 2024 Developer Survey), Web3 platforms can differentiate themselves by understanding user personas and needs and anticipating how they interact with documentation.
By understanding user personas and their development journeys, DevRel teams can effectively tailor resources to guide developers along different paths to success. For instance, a Web2 developer transitioning to Web3 can benefit from a structured learning path like the "Zero to Hero" course or video resources. By providing familiar tools and resources, such as CLI tools and APIs to interact with RPC, DevRel teams can bridge the gap between Web2 and Web3, making the transition smoother. This approach fosters trust, grows the developer community, and accelerates platform adoption.
How web3 Docs are Different from Traditional documentation
| Differentiator | Web3 | Web2 |
| Varied user segmentation | Documentation must be accessible to a wide audience and stakeholders, including developers, node operators, end-users, and potentially auditors. | Documentation is typically directed to closed and specific user segment |
| Accessibility | Documentation has to be accessible, adaptable, and maintainable by a community. | For enterprise software, docs are only accessible to specific users (subscribers, clients, etc.) |
| Technology | The complexity of the blockchain means explaining blockchain fundamentals, smart contracts, and cryptographic concepts is vital. | It does not give in-depth details of the base technology but focuses on the actionable details. |
| Philosophy | Decentralisation and Immutability: In Web3, Transparency, community, standardization, and accessibility drive the ecosystem's fundamental nature. | Centralisation and Mutability: Web 2 is slightly different. Its foundation is built around a centralised authority, and changes can be made directly to the database, which is mostly free. Monetisation is handled elsewhere. |
| Security | Emphasising security best practices and potential vulnerabilities is also of importance. | High-level architectures and models that keep the application safe. |
| Interoperability | Documenting how different blockchain systems interact is also essential. For example, document how inter-blockchain standards for things like tokens (ERC20, ERC721, etc.) allow entirely different systems to interact with each other with lower barriers to entry. | Focus is how the solution interacts with the customer/client. |
| Developer Experience (DX) | The rapidly evolving ecosystem means that documentation must be adaptable to frequent updates and changes. | Already at its peak state, DX in web2 is at a higher level of maturity than that of web3 |
| Community driven development | Encourage developer contributions and feedback. The ability to contribute code and tutorials, submit issues, and report bugs means developers can feel a sense of ownership and belonging to that ecosystem. | The service provider for the clientele or consumer usually leads this |
To create effective documentation experiences, deeply understand your documentation users. This requires comprehensive user research, considering a diverse audience.
Technical Users: Developers, Tech Leads, IT Support
Non-Technical Users: General Users, Customer Support
Decision-Makers: Executives influencing tool choices
In the next chapter in this series, we will explore how to conduct user research for documentation, tailor content based on different user journeys, and create an excellent information architecture that effectively onboards developers and users to your product.
Resources
Huge thanks to Brendan Graetz for the review of the series and feedback.
Subscribe to my newsletter
Read articles from Owanate Amachree directly inside your inbox. Subscribe to the newsletter, and don't miss out.
Written by
Owanate Amachree
Owanate Amachree
I’m a lead technical writer with over four years of experience helping global blockchain companies drive product adoption. Through high-quality product documentation, guides, and articles, I have empowered over 7,000 developers, users, and enterprise businesses to engage effectively with blockchain technologies. Currently serving as a Lead Technical Writer at RootstockLabs, I have authored and published over 50 guides and tutorials, significantly improving developer onboarding and user experience.