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

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