Developer documentation is an essential resource that provides developers with comprehensive information, guidance, and examples for effectively using APIs, frameworks, libraries, or software platforms. It's also a powerful tool in developer relations because it provides all the necessary information during the onboarding process, keeps your users informed on changes and plans, and helps you maintain relationships with your users, build a community, and encourage collaboration. Using a design thinking approach, this book aims to provide an easy to follow blueprint for building successful developer documentation drawing from the valuable insights gained while building the award winning platformOS developer portal.

You'll work with practical usable templates, workflows, and tools validated and peer-reviewed by international experts in the fields of documentation, technical writing, developer relations, and UX design. This book reveals the many factors that have to be considered while crafting developer documentation, such as hitting the right target audience, designing a seamless onboarding experience, selecting the right workflows and data analysis methods. You'll delve into this complex mix of topics, each with its unique considerations, and understand why it's challenging for those working on developer documentation to grasp the entire process, including all essential ingredients, tools, and resources.

• Examine how user research facilitates documentation development
• Utilize design thinking, community-driven documentation, and Docs as Code
• Understand editorial workflows and what happens at each step
• Write a style guide from scratch and use it for content production
• Review how methods and strategies fall into place during technical implementation

Here's a brief overview of each chapter, providing a comprehensive guide covering every aspect of developing effective developer documentation, including practical approaches, foundational principles, workflow management, and more.

1. Approaches: Even if you are starting something from scratch, you probably don’t have to start from zero: there is a good chance that other people have worked on something similar before, or came up with processes and solutions that you can apply to your project. The challenge is finding the approaches that would work for you. This chapter delves into various practical approaches, outlining their benefits and potential applications.
2. Foundations: Regardless of the current state of your developer documentation, whether you’re starting from scratch, rebuilding or improving your existing documentation, or fine-tuning a well-functioning documentation site, you can only expect good results if you build on solid foundations. This chapter emphasizes the crucial role user research plays in the discovery phase of building a developer documentation site. It introduces user research practices and processes to help you better understand your users, their goals, behaviors, and documentation needs.
3. Editorial Workflow: The editorial workflow encompasses how you create, edit, publish, and manage content. It is the foundation for the editorial experience you provide, including how you document the processes you developed and how you share it with your contributors. This chapter delves into the topic of creating an editorial workflow for your developer documentation site.
4. Content Production: Following the Content First approach means that you start developing content (or at least defining the structure of your content) relatively early on in your process before you start working on wireframes, layouts, or the technical implementation. This chapter focuses on the practical aspects of content production for developer documentation sites. It guides you on selecting an appropriate markup language, crafting a documentation style guide, and creating templates tailored to different content types. Additionally, the chapter emphasizes the significance of curating content tailored for onboarding various personas and underscores the importance of adhering to foundational SEO best practices.
5. Implementation: You laid a solid foundation for building your developer documentation by gaining an empathetic understanding of the needs of your target audience, planning your editorial workflow, and outlining the structure of your content. This chapter discusses how all these elements fall into place in the technical implementation when you’ll create wireframes, implement a design, develop the code base, and set up a deployment process.
6. Community: One of the approaches discussed in Chapter 1, “Approaches,” is community-driven documentation, which refers to a collaborative approach to documentation development where you aim to involve your users in all stages of the process. This chapter details the ways community members can assist, such as providing feedback, contributing content, and participating in user research. The chapter also describes what makes a great contributor experience, how various communication channels can be used to obtain valuable insights for documentation, and the role the documentation team plays in fostering a strong community culture.
7. Accessibility and Inclusion: I have mentioned accessibility throughout this book in connection with user research, the Docs-as-Code approach, reviews, and the documentation style guide. This chapter delves deeper into accessibility and inclusiveness to help you provide people with varying abilities, backgrounds, and circumstances the chance to engage with and make meaningful contributions to your developer documentation.
8. Sustainability: Based on total ICT emissions from the article How to stop data centres from gobbling up the world’s electricity compared with carbon emission by country, if the Internet was a country, it would be in the top ten of largest polluters. This chapter discusses why sustainability is essential, the characteristics of a sustainable Internet, the factors that make a website sustainable, and methods to reduce the environmental impact of your documentation site.
9. Team: It will require the collective effort of multiple team members to accomplish all the tasks described in this book. This chapter delves into the distinctive contributions that each member of your documentation team can make, ways in which you can help them bring their best to your project, and the available resources that can enhance everyone's understanding of developing developer documentation.
10. Measures of Success: While setting objectives, prioritizing tasks, and crafting your documentation, crucial questions emerge: How can you assess your success? How can you evaluate the tangible and intangible outcomes of your efforts? How can you determine the quality and effectiveness of your documentation? This chapter explores various metrics that can bolster your efforts toward enhancing your developer documentation.

Paul Ballard:

Crafting Docs for Success by Diana Lakatos provides invaluable insights into creating a top-tier developer documentation portal, drawing from examples of the award-winning platformOS portal. As part of the Design Thinking series, the book highlights the role of documentation as a standalone product, outlining clear stages in an iterative design process.

With the docs-as-code approach inherently at the core of that process, the author effectively fosters and encourages a culture where all contributors feel responsible for documentation. Starting with the foundations of each project, such as the conceptualisation of the target audience through personas, to in-depth exploration of technical implementation details, this book expertly navigates the often-treacherous mire of modern documentation portal development.

Crafting Docs for Success is an excellent resource for all audiences involved in technical communication. Newcomers will benefit from a comprehensive overview of each stage in the portal creation process, while seasoned veterans can use the book to elevate their current and future projects.

Bob Watson, PhD:

Diana's ability to present technical information precisely in an easy-to-read style is, in itself, a model to follow. As a bonus, you also get a thorough and complete technical writing reference about the journey she and her team undertook while developing the docs-as-code documentation for PlatformOS.

The book takes you through the steps as her team made design decisions, implemented the underlying software, and created the content for PlatformOS while sharing how decisions were made along the way. At just over 200 pages, it can cover only a little bit about everything. It does, however, cover enough of everything to be very useful. The limited space is used effectively with graphics and links to many additional resources for those who want to dive deeper into any particular topic.

Diana uses PlatformOS as the source of her examples as she explores the processes and decisions made along the way. She provides some insights into the decision-making process that was used so that the information can be adapted to other products and situations. Her book also includes lots of examples from which anyone could use to get started building out new topic templates or style guides. I especially found her coverage of Accessibility and Sustainability of documentation to be a welcome and valuable resource.

This type of guided tour behind the curtains as a new documentation site is developed is extremely helpful to all technical writers. No matter where you are in your technical writing journey, you're bound to find helpful insights and information.

Istvan Zoltan Szabo:

Crafting Docs for Success by Diana Lakatos is a masterful guide that meticulously dissects the methods of creating effective developer documentation.

The content is organized into a coherent flow, guiding readers through an end-to-end workflow. The chapters follow a clear progression from initial approaches and foundational concepts to advanced topics like community engagement, sustainability, accessibility, and inclusion. Each section ensures that readers can easily follow along and understand how the components fit into the broader picture. The structure not only increases readability but also ensures that no aspect of the docs process is overlooked.

Crafting Docs for Success is not primarily about theory; it is a story of a team making decisions while creating their documentation platform. It's rich with hands-on examples that bring the concepts to life. These examples provide practical insights and actionable steps, making it easier for readers to apply the findings to their own work. Whether you're drafting your style guide or refining a complex set of developer guides, the real-world applications presented in this book will help you.

The author's enthusiasm is truly inspirational. Her real-world experience is obvious, lending credibility to the pieces of advice presented and making the book not just informative but also engaging.

Diana Lakatos distills complex concepts into easily digestible explanations, ensuring that readers can grasp even the most intricate ideas without feeling overwhelmed. This is also a testament to her skills as a tech writer and makes the book accessible to both beginners and seasoned players on the field. She 'practices what she preaches', structuring her content with precision and adhering to best practices in the field. This approach highlights the book's credibility even more. It is worth emulating in any tech writer project.

The logical structure, hands-on examples, clear language, and inspirational tone make the book a must-read for anyone who wants to be an expert in this field. Crafting Docs for Success is a valuable resource that not only teaches the principles of effective documentation but also inspires readers to put these principles into practice This book will equip you with the tools and insights needed to create great developer documentation.

Documentation maintainers and managers, technical writers, developer relations practitioners and advocates, technical community managers, developer marketers, software developers and designers, and start-up founders, CTOs, and CEOs