Crafting Docs for Success: An End-to-End Approach to Developer Documentation (Design Thinking)

Developer documentation is a powerful tool in developer relations because it provides all the necessary information during the onboarding process and keeps your users informed on changes such as release notes, status reports and new and updated topics. Using a design thinking approach, this book aims to provide an easy to follow blueprint for building successful developer documentation by using the award winning platformOS developer portal as inspiration. 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 must be considered while crafting developer documentation, such as hitting the right target audience, designing a seamless onboarding experience, and 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 difficult for those working on developer documentation to understand the process, as well as all the necessary ingredients, tools, and resources to overcome that challenge. Crafting Docs for Success is your one-stop resource for empowering your team and community to contribute and help maintain your documentation, as well as further improve diversity and inclusion. What You'll Learn 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 Who This Book Is For Software developers and designers, documentation maintainers and managers, technical writers, developer relations practitioners and advocates, technical community managers, developer marketers, and start-up founders, CTOs, and CEOs Table of Contents About the Author About the Technical Reviewer Acknowledgments Introduction Chapter 1: Approaches Documentation As a Product Design Thinking The Phases of the Design Thinking Process Design Thinking in Your Developer Documentation Project Whole Process Each Area of Focus Docs as Code Docs as Code for Developer Documentation Docs-as-Code Benefits Community-Driven Documentation Content First Topic-Based Authoring and DITA Summary Chapter 2: Foundations Project Discovery User Research User Research Methodologies Competitive Analysis Target Audience Developers Other Target Audience Segments User Interviews Personas Content Inventory Sitemap Card Sorting Exercise Persona-Based Content Prioritization Summary Chapter 3: Editorial Workflow Editorial Workflow Example Step 1: Writing Content Step 2: Submitting Content Step 3: Review Step 4: Editing Step 5: Merging Changes Step 6: Deployment Issue Management Review Culture Summary Chapter 4: Content Production Markup Languages Documentation Style Guide Introduction Audience Writing Guidelines Format Images Videos Accessibility and Inclusive Language Templates Concept Topic Template Task Topic Template Quickstart Guides Tutorials Reference Topic Template Documentation Style Guide Checklist Changelogs and Release Notes Use Cases Legal Copy Developer Onboarding Search Engine Optimization Summary Chapter 5: Implementation Wireframes Layouts and Design Technical Implementation Git Static Site Generators API Documentation Generators platformOS Automation CI/CD Tests Summary Chapter 6: Community Contribution Ways to Contribute Feedback Feedback on Documentation Topics Content Contribution User Research Contributor Experience Communication Community Summary Chapter 7: Accessibility and Inclusion Website Accessibility Writing for Accessibility Guidelines for Structuring Content Guidelines for Accessible and Inclusive Language Plain Language Simplified Technical English Accessibility Reviews Summary Chapter 8: Sustainability What Would a Sustainable Internet Look Like? What Makes a Website Sustainable? Hosting Performance Image Management Video Management Fonts Web Caching User Experience Content Management Search Engine Optimization Third-Party Tools Summary Chapter 9: Team The Members of Your Documentation Team Documentation Lead Technical Writer/Editor UX Researcher Information Architect Interaction Designer UX Writer UX Designer UI Designer Developers Quality Assurance Automation and DocOps Project Management Educating Your Team Members Summary Chapter 10: Measures of Success Documentation Quality Information Quality Documentation Site Activity Linters Website Metrics and Analytics Business Value Success Summary Appendix: Tools and Resources Tools Docs as Code Content editor Website crawlers Digital whiteboards Auto-generated changelog Static site generators Documentation hosting platforms Wireframing, prototyping Sustainability Performance Accessibility Search Linters, automation tools for writing Specifications, references Markup languages Style guides API reference Version control Accessibility Inclusion Books, articles, courses Design Thinking Docs as Code Developer documentation User experience research Version control Sustainability Accessibility API documentation, technical writing Metrics Community, conferences Research papers Award programs Index 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 all 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.Crafting Docs for Success is your one stop resource for empowering your team and community to contribute and help maintain your documentation, as well as further improve diversity and inclusion. What You'll Learn 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 Who This Book Is For 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