Instead of just trying to put a bandaid on the existing problem, I dove deep into a first principles approach to improving the docs to discover what makes developer docs truly exceptional and what would really make the difference for our users and allow me to create a new suite of clear, user-friendly, & beautifully designed resources that would take the Paddle's developer experience to a new level.
In the realm of software development, the foundation of success lies with impeccable developer documentation. It's what makes the difference between smooth sailing for developers through the onboarding and implementation process and spending months and months in the wild west of integrating a new billing system. Developer docs can sometimes be wild, uncharted territory filled with cryptic, incomplete, or just plain baffling guides. The original Paddle Docs were no different.

The original docs have faced a lot of criticism over the years, which has contributed to a negative rating in the developer community and, as mentioned previously, resulted in many developers coming up with hacky solutions toward implementation. One recurring issue is an overall lack of clarity and organization, making it challenging for developers to find essential information or navigate through the material seamlessly. The absence of practical examples and real-world use cases is another notable shortcoming, hindering developers' ability to grasp the practical implementation of Paddle's services effectively. Additionally, some users have reported inconsistencies and inaccuracies within the documentation, further eroding trust in its reliability.

Aside from the experience, the overall design of the original docs left a lot to be desired. The design was messy, there were an abundance of text hierarchy inconsistencies and usage pattern inconsistencies that made them generally unpleasant to use. The original doc design was completely misaligned with the updated and modern direction the overall Paddle brand was taking, which made the docs look like they were forgotten about, or a complete afterthought in the product development cycle.

To get a better picture of what the market standard looks like I conducted a competitive analysis of developer documentation across industry leaders such as Stripe, GitHub, Lemon Squeezy, Plaid, Square, and others.

Overall, these top software companies set a high bar for documentation quality. Internet sentiment and reviews consistently highlight their documentation's clarity, completeness, and navigational ease. Developers commend the use of practical examples, code snippets, and clear explanations, which facilitate quick comprehension and implementation. The inclusion of extensive API reference guides, comprehensive tutorials, and community-driven support forums garners praise for fostering a supportive developer ecosystem.

Most competitor's docs lacked strong visual styling and it most cases were treated more like an instruction manual for some boring technical equipment, rather than something beautiful, engaging, and delightful to read and learn from. This presented an opportunity to differentiate ourselves in the market.

Of course, developers are the core audience, relying on these docs for comprehensive technical guidance, code examples, and troubleshooting existence, as well as a thorough understanding of how Paddle works and what they need to know in order to implement it. To engage with this audience effectively, the docs should priorities clarity, concise code snippets, and hands-on tutorials.

CTOs, CPOs, and product managers play pivotal roles in decision-making regarding the implementation of Paddle's services. For this audience, the documentation should offer high-level overviews, case studies, and cost-benefit analyses, highlighting the strategic advantages of choosing Paddle.

Solution architects and support agents rely on in-depth technical insights, system architecture diagrams, integration best practices, FAQs, troubleshooting guides, and real-world use cases, as well as a list of common errors, to resolve issues promptly and enhance customer satisfaction.

Account executives and sales teams use developer docs as powerful marketing tools, especially when talking to highly technical potential customers. Assets such as case studies showcasing successful implementations, ROI calculations, and competitive advantages can empower AEs to effectively communicate the value prop of Paddle's services to potential clients and enhance their ability to drive business growth.

Throughout the project, I conducted and led a series of rigorous user testing sessions to shape our developer documentation effectively. These sessions involved a multifaceted approach, including internal surveys and interviews with our CTO, developers, and solution architects, as well as external testing using the UserTesting.com platform.

Below you'll find the Miro board put together during one the workshops I led to gather all of the questions we wanted to ask to our user testing panels, followed by the results of those questions and interviews.

Good documentation provides thorough coverage of a product's features, API endpoints, and functionality, ensuring developers have access to all necessary information. Clear and concise language is another crucial aspect, as it aids in comprehension and reduces ambiguity.

Good developer documentation anticipates the needs of its audience, catering not only to experienced developers but also to those with varying levels of expertise. It should offer progressive levels of detail, from introductory guides to advanced topics, accommodating a broad spectrum of users. Additionally, fostering a collaborative environment, such as user forums and community contributions, can enrich the documentation by incorporating real-world insights and collective problem-solving.

The best developer documentation evolves alongside the product, adapting to changes and user feedback. Regular updates, versioning, and a responsive feedback loop with the developer community are essential to maintaining documentation's relevance and utility over time.

It was important to me to treat the docs with high quality design integrity, both because I have high standards regarding my visual design output and because this approach would be something that would differentiate our docs from the rest of our competitive landscape.

In today's competitive tech landscape, developer documentation is often the first interaction potential users have with a product or service. Therefore, it should not only serve as a technical guide but also as a reflection of the brand's quality and commitment to user experience. To instill an overall high-quality marketing approach, I wanted the documentation to feature polished, visually appealing design, consistent with the brand's aesthetics. It also needed to convey the brand's messaging, values, and mission clearly, establishing a sense of trust and credibility.

The docs sit in a unique position between the product and the marketing brand, and needed to seamlessly integrate into both environments, which each has a distinct visual direction. To harmonize the typography, color palette, and iconography while ensuring a consistent and recognizable visual language, I created a custom design system that took the technical elements of the product design system such as typefaces and UX element functionality (e.g. button states) with the more visual elements of the marketing brand (e.g. color palette), and expanded on each of these to a degree to strategically create a unique visual voice for the dev docs.

Over the course of the project, I ran several workshops and brainstorming sessions with the members of my team (other designers, my copywriter, my product manager, and my engineering partner) to discuss a number of different challenges we had in front of us, including how to tell the story of how Paddle works to a user or potential customer and the value of doing so, narrowing down who our target personas were, and many others. The post-it note aftermath of one of these sessions can be seen below.

I also continuously put early versions of the docs in front of trusted users to pulse check how they viewed the version in front of them, what might be missing, and also what they loved and found valuable. The collaboration of these stakeholders was instrumental in uncovering potential gaps, inconsistencies, usability issues, and also possible areas for growth and opportunities to shine in the market.

Early iterations of the new developer documentation served as the foundation for our usability testing sessions. These early designs were aimed at capturing the essence of my vision, while remaining open to feedback and refinement. As insights from the testing sessions poured in, we iterated and evolved the design significantly. We recognized the need for a more modern, clean, and visually appealing aesthetic that not only aligned with our product's branding but also enhanced the overall user experience.

The end result was a visually striking and user-friendly documentation system that not only met the technical needs of our users but also resonated with them on an aesthetic level, marking a pivotal milestone in our journey towards providing an exceptional developer resource.

I designed custom illustrations, with their own visual language, that not only aligned seamlessly with the dev docs brand but also injected more visual appeal into the site.

They were strategically placed to help users contextualize products and information, making complex concepts more accessible and relatable. These visuals transformed the documentation from a static resource into a dynamic and compelling experience, visually guiding users through intricate processes and enhancing their understanding.

By treating it as a brand touchpoint and marketing asset, Paddle's docs not only serve as a technical guide but also amplifies the company's values and commitment to user satisfaction. The careful integration of the product design system and marketing brand has created a visually appealing and consistent experience that resonates with developers, decision-makers, and support agents alike.

Prioritizing the user journey within the documentation has streamlined the integration process for developers, reinforcing their confidence and empowerment. The culmination of these efforts has had a profound impact on the company, boosting user engagement by around 25% and reducing support tickets by about 40% during the onboarding process following the launch of our new billing platform.