Learn to integrate programming with good documentation. This book teaches you the craft of documentation for each step in the software development lifecycle, from understanding your users’ needs to publishing, measuring, and maintaining useful developer documentation.
Well-documented projects save time for both developers on the project and users of the software. Projects without adequate documentation suffer from poor developer productivity, project scalability, user adoption, and accessibility. In short: bad documentation kills projects.
Docs for Developers demystifies the process of creating great developer documentation, following a team of software developers as they work to launch a new product. At each step along the way, you learn through examples, templates, and principles how to create, measure, and maintain documentation―tools you can adapt to the needs of your own organization.
What You'll Learn
• Create friction logs and perform user research to understand your users’ frustrations
• Research, draft, and write different kinds of documentation, including READMEs, API documentation, tutorials, conceptual content, and release notes
• Publish and maintain documentation alongside regular code releases
• Measure the success of the content you create through analytics and user feedback
• Organize larger sets of documentation to help users find the right information at the right time
Who This Book Is For
Ideal for software developers who need to create documentation alongside code, or for technical writers, developer advocates, product managers, and other technical roles that create and contribute to documentation for their products and services.
Author(s): Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne, David Nunez, Heidi Waterhouse
Edition: 1
Publisher: Apress
Year: 2021
Language: English
Commentary: Vector PDF
Pages: 240
City: New York, NY
Tags: Management; Quality Control; Psychology; Maintanability; Best Practices; User Experience; Documentation; Writing; User Stories; User Feedback
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
