Docs for developers : an engineer's field guide to technical writing

Description

Table of Contents About the Authors Acknowledgments Foreword Introduction Chapter 1: Understanding your audience Corg.ly: One month to launch The curse of knowledge Creating an initial sketch of your users Defining your users’ goals Understanding who your users are Outline your users’ needs Validate your user understanding Using existing data sources Support tickets Collecting new data Direct interviews Developer surveys Condensing user research findings User personas User stories User journey maps Creating a friction log Summary Chapter 2: Planning your documentation Corg.ly: Creating a plan Plans and patterns Content types Code comments READMEs Getting started documentation Conceptual documentation Procedural documentation Tutorials How-to guides Reference documentation API reference Glossary Troubleshooting documentation Change documentation Planning your documentation Summary Chapter 3: Drafting documentation Corg.ly: First drafts Confronting the blank page (or screen) Setting yourself up for writing success Choosing your writing tools Breaking through the blank page Defining your document’s title and goal Creating your outline Meeting your reader’s expectations Completing your outline Creating your draft Headers Paragraphs Procedures Lists Callouts Writing for skimming State your most important information first Break up large blocks of text Break up long documents Strive for simplicity and clarity Getting unstuck Let go of perfectionism Ask for help Highlight missing content Write out of sequence Change your medium Working from templates Finishing your first draft Summary Chapter 4: Editing documentation Corg.ly: Editing content Editing to meet your user’s needs Different approaches to editing Editing for technical accuracy Editing for completeness Editing for structure Editing for clarity and brevity Creating an editing process Reviewing your document first Requesting a peer review Requesting a technical review Receiving and integrating feedback Giving good feedback Summary Chapter 5: Integrating code samples Corg.ly: Showing how it works Using code samples Types of code samples Principles of good code samples Explained Concise Clear Usable (and extensible) Trustworthy Designing code samples Choosing a language Highlighting a range of complexity Presenting your code Tooling for code samples Testing code samples Sandboxing code Autogenerating samples Summary Chapter 6: Adding visual content Corg.ly: Worth a thousand words When words aren’t enough Why visual content is hard to create Comprehension Accessibility Performance Using screenshots Common types of diagrams Boxes and arrows Flowcharts Swimlanes Drawing diagrams Start on paper Find a starting point for your reader Use labels Use colors consistently Place the diagram Publishing a diagram Get help with diagrams Creating video content Reviewing visual content Maintaining visual content Summary Chapter 7: Publishing documentation Corg.ly: Ship it! Putting your content out there Building a content release process Creating a publishing timeline Coordinate with code releases Finalize and approve publication Decide how to deliver content Announce your docs Planning for the future Summary Chapter 8: Gathering and integrating feedback Corg.ly: Initial feedback Listening to your users Creating feedback channels Accept feedback directly through documentation pages Monitor support issues Collect document sentiment Create user surveys Create a user council Converting feedback into action Triaging feedback Step one: Is the issue valid? Step two: Can the issue be fixed? Step three: How important is the issue? Following up with users Summary Chapter 9: Measuring documentation quality Corg.ly: Tuesday after the launch Is my documentation any good? Understanding documentation quality Functional quality Accessible Purposeful Findable Accurate Complete Structural quality Clear Concise Consistent How functional and structural quality relate Creating a strategy for analytics Organizational goals and metrics User goals and metrics Documentation goals and metrics Tips for using document metrics Make a plan Establish a baseline Consider context Use clusters of metrics Mix qualitative and quantitative feedback Summary Chapter 10: Organizing documentation Corg.ly: The next release Organizing documentation for your readers Helping your readers find their way Site navigation and organization Sequences Hierarchies Webs Bringing it all together Landing pages Navigation cues Organizing your documentation Assess your existing content Outline your new information architecture Migrate to your new information architecture Maintaining your information architecture Summary Chapter 11: Maintaining and deprecating documentation Corg.ly: A few releases later Maintaining up-to-date documentation Planning for maintainability Align documentation with release processes Assign document owners Reward document maintenance Automating documentation maintenance Content freshness checks Link checkers Linters Reference doc generators Removing content from your docset Deprecating documentation Deleting documentation Summary Appendix A: When to hire an expert Meeting a new set of user needs Increasing support deflections Managing large documentation releases Refactoring an information architecture Internationalization and localization Versioning documentation with software Accepting user contributions to documentation Open-sourcing documentation Appendix B: Resources Courses Templates Style guides Automation tools Visual content tools and frameworks Blogs and research Books Communities Bibliography Index