Introduction: A Developer’s Morning Integration

It’s 9 AM on a crisp Tuesday morning, and Alex, a Web3 developer, is starting his day with a steaming cup of espresso. Known for his unwavering ability to get sidetracked, he’s diligently working on integrating Lido, a leading decentralized finance platform, into his dApp. As he scrolls through Lido’s documentation, he needs to test various smart contract functions to ensure smooth integration.

Without the Bonadocs widget, Alex’s day is predictably interrupted by his need to open a separate testing environment, switch between multiple tabs, and constantly shift his focus. Despite his best efforts, he’s always one Slack message away from losing his train of thought. These interruptions not only break his concentration but also slow down his development process, adding unnecessary stress and extending his work hours.

For developers like Alex, and the product documentation teams aiming to increase the adoption of their platforms, these inefficiencies are critical barriers. The Bonadocs widget is designed to overcome these challenges, providing a seamless testing solution embedded directly within the documentation.

Problem Statement

Developers integrating third-party platforms like Lido face the challenge of constant context switching between documentation and testing environments. This inefficiency disrupts their workflow, increases cognitive load, and slows down integration processes. Our goal was to create a solution that allows developers to test smart contracts directly within the documentation, reducing these disruptions and enhancing productivity.

Research Objective

To understand the primary tasks, goals, and pain points of Web3 developers when integrating and testing smart contracts within documentation, and to identify how an integrated testing solution like the Bonadocs widget can improve their workflow.

Methodology

We conducted Jobs-to-be-Done (JTBD) interviews with Web3 developers to gather qualitative insights. The interviews focused on understanding their daily tasks, challenges, and the outcomes they seek when working with smart contracts.

Participant Details

We interviewed 8 Web3 developers from various mid-sized blockchain companies. Participants had an average of 5 years of software development experience and 2 years of experience in Web3 development. They used a range of tools including Solidity, JavaScript, React, Node.js, MetaMask, Truffle, Remix, and Ganache.

Screenshot of a user-interview with a developer (anonymous).

Key Findings

1. Tasks and Goals

   • "Testing smart contracts is a constant part of my workflow. I need to ensure each function works as expected before moving on."

   • "When integrating new features, I frequently refer to documentation and test the contracts side by side to make sure everything aligns."

2. Pain Points

   • "Switching between my code editor, testing environment, and documentation is a huge hassle. It breaks my concentration every time."

   • "It’s frustrating when I have to juggle multiple tabs and tools just to test a simple contract. It feels like I spend more time managing tools than actually coding."

   • "A single Slack message can throw me off track for a while, especially when I’m deep into testing and have to switch contexts."

3. Desired Outcomes

   • "An integrated testing tool within the documentation would be a game-changer. It would save so much time and keep me focused."

   • "If I could test smart contracts directly in the docs, it would streamline my workflow and reduce the cognitive load of switching between tools."

4. Impact of Bonadocs Widget

   • "Having a tool like the Bonadocs widget would simplify my work. I could test contracts right there without jumping through hoops."

   • "This widget would definitely speed up my development process and help me stay in the zone. It's exactly what we need to improve efficiency."

     
     

   

   
   

   A screenshot of a table containing some of the questions I asked during the JTBD interviews?

Screenshot of the User Journey map we came up with insights from the JTBD interviews. See full version here

Application of Findings

The insights gained from the JTBD interviews informed the design of the Bonadocs widget. By embedding interactive testing features directly into the documentation, the widget addresses the key pain points identified in the research. It helps developers like Alex test smart contracts in real-time without leaving the documentation interface, leading to a more efficient and productive workflow.

Solution Development and Testing

Design Process

After identifying the pain points and desired outcomes from the JTBD interviews, I set out to create the Bonadocs widget. The goal was ambitious: to embed a seamless, interactive testing environment directly within the Lido documentation. This meant enabling developers to test smart contracts in real-time without leaving the page. But we knew it wouldn't be easy. We faced several uncertainties right from the start.

Initial Challenges

Our team grappled with several questions as we embarked on this journey:

• Would embedding a widget within documentation disrupt the existing user experience?

• Could we make the interface intuitive enough for developers to use without a steep learning curve?

• How would we handle complex transaction parameters within the widget?

• Would querying the mainnet directly from the documentation be feasible and secure?

<Include screenshot of moodboard>

Solution Development

To tackle these challenges, we used affinity diagramming to organize and prioritize the feedback we received from the initial round of usability testing. By clustering similar pieces of feedback, we identified common themes and critical pain points.

Screenshot of an affinity diagram

With these insights, we moved into the rapid prototyping phase. Leveraging the existing design system from the Bonadocs team, we quickly developed low-fidelity prototypes to explore different design solutions. Rapid prototyping allowed us to test these solutions with users early and often, making it possible to iterate and refine the designs efficiently.

Screenshot of a typography system that is part of the Bonadocs design system which was available to me and enabled to prototype rapidly (rapid prototyping).

rough sketches of the widget

low fidelity wireframes for querying a method in a smart contract

moodboard

First explorations of the high fidelity ui

Userflow Reel

Screen record of the first UI exploration flow.

Usability Testing: Round Two

With the refined prototypes, we conducted a second round of usability testing. This round focused on validating the improvements and gathering further feedback. The key enhancements included:

1. Expanded View with Parameters: Allowing developers to enter transaction parameters directly within the widget.

2. Mainnet Query Option: Enabling real-life simulations by querying the mainnet, which required wallet connection.

3. Simplified Wallet Connection Flow: Adding an indicator to show whether the wallet is connected or not.

4. Method Descriptions: Incorporating an info tooltip to describe method parameters.

5. Const Transaction Params View: Introducing a tab view for const transaction parameters like From (address), Gas, and Gas price.

6. Read/Write Method Indicators: Clearly distinguishing between read and write methods.

During this second round of testing, participants praised the enhanced widget for its ease of use and the ability to test methods directly in the documentation, especially with real-life simulations on the mainnet. Here are some snapshots of their feedback:

These insights and feedback guided our final round of refinements, ensuring the Bonadocs widget was optimized for usability and productivity.

Userflow Reel – Revised

A screen record of the revised userflow.

Key Features and Their Impact

1. Mainnet Query Option

Feature Description: The Bonadocs widget includes an option to query the mainnet directly from the documentation. Developers can connect their wallets and run real-life simulations, which are critical for accurate testing.

Value and Impact:

• Realism: Testing on the mainnet provides developers with realistic results, ensuring their smart contracts work as intended in a live environment.

• Trust: Businesses can trust that their smart contracts are thoroughly tested and reliable before deployment, reducing the risk of costly errors.

• User Experience: The seamless integration of wallet connection and mainnet queries enhances the overall user experience, making the testing process more streamlined and efficient.

2. Adding Array Properties

Feature Description: The widget allows developers to add array properties, which can carry tuples of parameters. This feature is visible in the method parameters section, where developers can input complex data structures required for their smart contract methods.

Value and Impact:

• Flexibility: This feature supports the testing of complex smart contract methods, accommodating various data structures and ensuring comprehensive testing.

• Productivity: Developers can efficiently input and test complex parameters without leaving the documentation, improving workflow and reducing errors.

• Scalability: By supporting arrays and tuples, the widget can handle more sophisticated use cases, making it suitable for a wide range of smart contract applications.

3. Switching Between Method and Transaction Parameters

Feature Description: The widget provides an intuitive interface for switching between method parameters and transaction parameters. This is crucial for developers to accurately simulate different aspects of smart contract execution.

Value and Impact:

• Clarity: Clearly separating method and transaction parameters helps developers understand and manage the different aspects of their smart contract tests.

• Ease of Use: The intuitive interface reduces the learning curve, making it easier for developers to get started and achieve their testing goals.

• Efficiency: By organizing parameters logically, the widget minimizes confusion and potential errors, leading to more accurate and reliable testing outcomes.

Impact

Industry Recognition

Selected as part of the maiden Consensys fellowship program, showcasing the innovative approach and value of the Bonadocs widget in the web3 space.

Adoption by Key Players

Now actively used and supported by prominent teams such as Arbitrum, Superfluid, Compound Finance, Optimism, Base, Paycrest, and others, signifying its relevance and effectiveness in enhancing developer experiences.

Pioneering Web3 DX

We’re breaking new ground in web3 developer experiences with features like the playground, docgen, and widgets, which are unparalleled in the industry, offering a comprehensive solution that supports both the development and distribution of protocols.