Table of Contents
• Getting Started
• Researching documentation
• Understanding your users
• Cultivating empathy
• Understanding user desires, user needs, and company needs
• Recruiting users for research
• Research methods
• Reading code comments
• Trying it out
Friction logs
• Running diverse and inclusive focus groups and interviews
• User journey mapping
• Identifying and working with stakeholders
• Finding your experts
• Collaborative documentation development
• Learning from existing content
• The value of design documents
• Finding examples in industry
• Designing documentation
• Defining your initial set of content
• Deciding your minimum viable documentation
• Drafting test and acceptance criteria
• Understanding content types
• Concepts, tutorials and reference documentation
• Code comments
• API specifications
READMEs
• Guides
• Release notes
• Drafting documentation
• Setting yourself up for writing success
• Who is this for? Personas, requirements, content types
• Definition of done
• How to iterate
Tools and tips for writing rough drafts
• Understanding your needs
• Choosing your writing tools (handwriting, text-only, productivity/measurement writing tools)
• “Hacks” to get started drafting content
• Mechanics
• Headings
• Paragraphs
• Lists
Notes and warnings
• Conclusions/tests
• Using templates to form drafts
• Purpose of a template
• How to derive a template from existing docs
How to take templates into text
• Gathering initial feedback
• Feedback methods
• Integrating feedback
• Getting feedback from difficult contributors
Editing content for publication
• Determine destination
• Editing tools (Grammarly, linters, etc)
• Declaring good enough
• Recap, strategies, and reassurance
Structuring sets of documentation
• Where content types live
• Concepts, tutorials and reference documentation
• Code comments
• API specifications
READMEs
• Guides
• Release notes
• Designing your information architecture
• Content information architecture styles
• Designing for search
• Creating clear, well-lit paths through content
• User testing and maintenance
• Planning for document automation
• Integrating code samples and visual content
• Integrating code samples
• When and why to use code samples
• Creating concise, usable, maintainable samples
• Standardising your samples
• Using visual content: Screenshots, diagrams, and videos
• When your documentation may need visual content
• Making your visual content accessible
• Integrating screenshots, diagrams
• Videos
• Measuring documentation success
• How documentation succeeds
• Measuring different types of documentation quality
• Structural Quality
• Functional Quality
• Process Quality
• Measuring what you want to change
Drawing conclusions from document metrics
• Working with contributors
• Defining how decisions are made
• Deciding on a governance structure
• Writing an effective Code of Conduct
• Choosing a content licence
• Code licenses
• Content licences
Building and enforcing a style guide
• Editing submitted content and giving feedback
• Setting acceptability criteria
• Editing for accessibility and inclusion
• Editing for internationalization and translation
• Giving actionable feedback
• Planning and running a document sprint
• Maintaining documentation
• Creating a content review processes
• Assigning document owners
• Performing freshness checks on content
Responding to documentation issues
• Separating documentation issues from product issues
• Responding to users
• Automating document maintenance
• Automating API and reference content
• Using doc linters
• Deleting and archiving content
• Wrapping up