Docs-as-Ecosystem: The Community Approach to Engineering Documentation

Investing in engineering documentation (Docs) means investing in community user experience. This book teaches readers how mastering the docs-as-code ecosystem empowers communities to understand better their favorite products and Open-Source (OSS) technologies better. Author Alejandra Quetzalli believes that “docs-as-ecosystem” represents a more comprehensive and collaborative approach to documentation development than “docsas- code” because it recognizes that documentation is more than just code. Docs involve technical writing, design, community feedback, community management, accessibility, SEO, UX, and today... even Artificial Intelligence tools! The word ecosystem promotes a paradigm where we treat documentation as a complex and dynamic system that must be managed and nurtured. In this book, you’ll acquire practical skills such as creating public style guides, incorporating responsive and accessible design, designing user flows and information architecture, retrieving user feedback, and setting up Docs analytics. You’ll learn to identify the difference in work processes between maintaining Docs for a product versus an OSS technology. You’ll discover the secrets to managing technical writers and OSS contributions, all while building a thriving Docs community. To end on a futuristic note, you’ll discover why technical writers who harness Artificial Intelligence (AI) tools (i.e., ChatGPT) need not fear a robot uprising anytime soon. What You'll Learn Examine accessibility and the user experience Understand Information architecture Review docs-as-ecosystem processes Manage technical writers Oversee OSS Docs contributions Retrieve and integrate user feedback Build Docs and Education communities Who This Book is For Developers of all levels, VPs of Product/Engineering, Product Managers, and Designers, Table of Contents About the Author About the Technical Reviewer Acknowledgments Endorsements Preface: Why Docs-as-Ecosystem? Chapter 1: Accessibility Why the Need? Where Does Accessibility Begin for Docs? Semantic HTML Ambiguous or Incomplete Anchor Text Blinking or Flashing Content Color-Blind-Friendly Palettes Duplicate Alt-Text Duplicate Form Label Empty Buttons Empty Heading Tag Empty Link Empty or Missing Table Header Image Missing Alternative Text Incorrect Heading Order Insufficient Color Contrast Missing Language Declaration Missing Transcript Moving Content (Slides/Carousel) Justified Text Small Font Sizes Free Screen Readers and Accessibility Testing Tools Extra Resources In Closing Chapter 2: Information Architecture Why the Need? Content Buckets Diátaxis Framework User Flows Search Functionality In Closing Chapter 3: Search Engine Optimization Why the Need? On-Page Optimization Techniques Headers Page Titles and Meta Descriptions Keyword Research and Optimization URL Structure Internal Linking Image Optimization Navigation Page Loading Time Sitemaps Off-Page Optimization Techniques Backlinking Robots.txt File Crawling and Indexing Sitemaps Online Forums and Social Media Common SEO Challenges Duplicate Content and Canonical Pages Internationalization (i18n) The Rise of Artificial Intelligence in SEO Machine Learning in Search Algorithms Natural Language Processing, Voice Search, and Chatbots AI Search Engines In Closing Chapter 4: User Interface and User Experience Why the Need? Collaboration with Designers Docs Home Page Responsive Design Colors Typography Navigation Search Diagrams Error Handling and Messaging In Closing Chapter 5: Documenting APIs Why the Need? Structuring API Docs Organizing by Functionality or Endpoint API Requests and Responses API Versioning and Release Notes API Authentication Testing API Docs and Error Handling Testing Error Handling Tools for Testing and Documenting APIs More Resources Who Owns API Docs? In Closing Chapter 6: Documenting SDKs Why the Need? Structuring SDK Documentation Installation and Setup SDK Usage Guide SDK Integration Guide SDK Reference SDK Tutorials and Code Examples SDK Release Notes Who Owns SDK Docs? More Resources In Closing Chapter 7: Integrating Docs into CI/CD Pipelines Why the Need? Documentation As Code Versioning Documentation Reviewing Documentation Testing Documentation Continuous Improvement and Community Feedback CI/CD Tools and Frameworks Who Owns Docs CI/CD Pipelines? In Closing Chapter 8: Crafting Public Style Guides Why the Need? Components of Style Guides Define Target Audience Style Guide Outline Template Who Designs Docs Style Guides? Who Owns Docs Style Guides? Extra Resources In Closing Chapter 9: Managing OSS Docs Contributions Why the Need? Join OSS Docs Programs Best Practices for Building Safe and Thriving OSS Docs Communities Adhere to the OSS Project’s Code of Conduct Mentor Junior Contributors Create Yearly OSS Docs Mentorship Programs Create Social Media Posts and Videos Host Local and In-Person Events Find Your Community Docs Questions Managing Contributions to OSS Docs Onboarding New OSS Docs Contributors Who Owns Managing OSS Docs Contributions? In Closing Chapter 10: Retrieve Community Feedback and Analytics Why the Need? Best Practices for Retrieving Community Feedback Create Social Media Posts Host Local and In-Person Events Find Your Community Docs Questions Public GitHub Discussions and Surveys Methods for Retrieving Community Feedback Docs Issue and Docs Bug Templates Docs Pull Request Template Feedback Cards Feedback Widgets Slack Bot Discord Bot Analytics Platforms Some Analytics Platforms That You May Want to Consider Who Owns Retrieving Community Feedback? OSS Docs Enterprise Docs Who Owns Monitoring Docs Analytics? OSS Docs Analytics Enterprise Docs Analytics In Closing Chapter 11: Prioritize Documentation Requests Why the Need? Stakeholders in the Docs Ecosystem Model Risks of Not Prioritizing Documentation Requests Tools for Prioritizing Documentation Requests Criteria for Prioritizing Requests Weigh Different Criteria Against Each Other When Prioritizing Requests Evaluate the Impact of a Docs Request on Project Timelines, Product Functionality, or Compliance Common Criteria Used in Engineering Documentation Requests Docs Request Evaluation Process Estimate Time and Effort Required to Fulfill Requests Communicate Evaluation Results to Stakeholders Effective Communication in Prioritizing Requests Manage Expectations and Respond to Changes in Priorities Ensure Feedback Is Actionable and Effective Who Owns Prioritizing Docs Requests? Prioritizing Docs Requests in OSS Prioritizing Docs Requests in Enterprise In Closing Chapter 12: Open Community Communication Channels Why the Need? Types of Open Community Communication Channels Online Forums Mailing Lists Chat Rooms Social Media Platforms Tools for Managing Open Community Communication Channels Best Practices for Managing Open Community Communication Channels Communities Using Open Communication Channels Future of Open Community Communication Channels Artificial Intelligence (AI) to Moderate Forums Increasing Use of Video and Live Streaming Who Owns Managing Open Community Communication Channels? Managing OSS Communication Channels Managing Enterprise Communication Channels In Closing Chapter 13: Managing Technical Writers Why the Need? Radical Kindness, Honesty, and Flexibility When Managing Technical Writers The Power of Being Specific Be Understanding When Personal Issues Arise Embracing Diverse Work Styles and Preferences Be Patient with Learning Curves and Support Your Writers Recognize Writers’ Effort and Hard Work Hiring Technical Writers Training Technical Writers Overseeing Technical Writers Nurturing Technical Writers Accidental Plagiarism Dealing with Challenges Assume Lack of Knowledge or Experience Acknowledge Growth and Encourage Continuous Feedback Address Frequent Noncommunication or Low-Quality Work Protecting Your Team from Narcissistic or Toxic Team Members Who Owns Managing Technical Writers? Managing Technical Writers in OSS Managing Technical Writers in Enterprise Managing Technical Writers in Startups In Closing Chapter 14: The Future of ChatGPT and AI in Docs Why the Need? Opens the Field for Juniors Accelerates Research Process Jobs Change to Editing and Community-Building Focus Cite and Give Attribution to ChatGPT and AI Tools Fact-Checking AI: Understanding Limitations and Potential Risks of ChatGPT and AI Tools Who Owns Fact-Checking AI Resources? More Resources In Closing A Parting Poem Index Investing in engineering documentation (Docs) means investing in community user experience. This book teaches how mastering the proposed docs-as-ecosystem model empowers communities to understand better their favorite products and Open-Source (OSS) technologies. Quetzalli believes that "docs-as-ecosystem" represents a more comprehensive and collaborative approach to documentation development than "docs-as-code" because it recognizes that documentation is more than just code. Docs involve technical writing, design, community feedback, community management, accessibility, SEO, UX, and today even Artificial Intelligence tools! The word ecosystem promotes a paradigm where documentation is treated as a complex and dynamic system that must be managed and nurtured. In this book, you'll acquire practical skills such as creating public style guides, incorporating responsive and accessible design, designing user flows and information architecture, retrieving user feedback, and setting up Docs analytics. You'll learn to identify the difference in work processes between maintaining Docs for a product versus an OSS technology. You'll discover the secrets to managing technical writers and OSS contributions, all while building a thriving Docs community. To end on a futuristic note, you'll discover why technical writers who harness Artificial Intelligence (AI) tools (i.e., ChatGPT) need not fear a robot uprising anytime soon. This Book is For Developers of all levels, VPs of Product/Engineering, Product Managers, and Designers, and OSS community members.