Docs for Developers: An Engineer's Field Guide to Technical Writing

1. Getting Started

2. Researching documentation

1. Understanding your users

2. Cultivating empathy

3. Understanding user desires, user needs, and company needs

4. Recruiting users for research

3. Research methods

1. Reading code comments

2. Trying it out

Friction logs

3. Running diverse and inclusive focus groups and interviews

4. User journey mapping

4. Identifying and working with stakeholders

1. Finding your experts

2. Collaborative documentation development

5. Learning from existing content

1. The value of design documents

2. Finding examples in industry

Designing documentation

1. Defining your initial set of content

2. Deciding your minimum viable documentation

3. Drafting test and acceptance criteria

Understanding content types

Concepts, tutorials and reference documentation

Code comments

API specifications

READMEs

Guides

Release notes

Drafting documentation

1. Setting yourself up for writing success

2. Who is this for? Personas, requirements, content types

3. Definition of done

4. How to iterate

Tools and tips for writing rough drafts

1. Understanding your needs

2. Choosing your writing tools (handwriting, text-only, productivity/measurement writing tools)

3. "Hacks" to get started drafting content

Mechanics

Headings

Paragraphs

Lists

Notes and warnings

Conclusions/tests

Using templates to form drafts

1. Purpose of a template

2. 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

1. Determine destination

2. Editing tools (Grammarly, linters, etc)

3. Declaring good enough

Recap, strategies, and reassurance

Structuring sets of documentation

1. Where content types live

2. Concepts, tutorials and reference documentation

3. Code comments

4. API specifications

READMEs

5. Guides

6. Release notes

Designing your information architecture

1. Content information architecture styles

2. Designing for search

3. Creating clear, well-lit paths through content

User testing and maintenance

Planning for document automation

Integrating code samples and visual content

1. Integrating code samples

2. When and why to use code samples

3. Creating concise, usable, maintainable samples

4. Standardising your samples

Using visual content: Screenshots, diagrams, and videos

1. When your documentation may need visual content

2. Making your visual content accessible

3. Integrating screenshots, diagrams

4. Videos

Measuring documentation success

How documentation succeeds

Measuring different types of documentation quality

1. Structural Quality

2. Functional Quality

3. Process Quality

Measuring what you want to change

Drawing conclusio

Author: Jared Bhatti, Zachary Sarah Corleissen, Jen Lambourne
Publisher: Apress
Published: 09/10/2021
Pages: 240
Binding Type: Paperback
Weight: 0.79lbs
Size: 9.21h x 6.14w x 0.53d
ISBN13: 9781484272169
ISBN10: 1484272161
BISAC Categories:
- Computers | Internet | Web Programming
- Computers | Programming | Open Source

About the Author

Jared Bhatti

Jared is a Staff Technical Writer at Alphabet, and the co-founder of Google's Cloud documentation team. He's worked for the past 14 years documenting an array of projects at Alphabet, including Kubernetes, App Engine, Adsense, Google's data centers, and Google's environmental sustainability efforts. He currently leads technical documentation at Waymo and mentors several junior writers in the industry.

Zachary Sarah Corleissen

Zach began this book as the Lead Technical Writer for the Linux Foundation and ended it as Stripe's first Staff Technical Writer. Zach served as co-chair for Kubernetes documentation from 2017 until 2021, and has worked on developer docs previously at GitHub, Rackspace, and several startups. They enjoy speaking at conferences and love to mentor writers and speakers of all abilities and backgrounds.

Heidi Waterhouse

Heidi spent a couple decades at Microsoft, Dell Software, and many, many startups learning to communicate with and for developers. She currently works as a principal developer advocate at LaunchDarkly, but was reassured to find that technical communication is universal across all roles.

David Nunez

David heads up the technical writing organization at Stripe, where he founded the internal documentation team and wrote for Increment magazine. Before Stripe, he founded and led the technical writing organization at Uber and held a documentation leadership role at Salesforce. Having led teams that have written about cloud, homegrown infrastructure, self-driving trucks, and economic infrastructure, he's studied the many ways that technical documentation can shape the user experience. David also acts as an advisor for several startups in the knowledge platform space.

Jen Lambourne

Jen leads the technical writing and knowledge management discipline at Monzo Bank. Before her foray into fintech, she led a community of documentarians across the UK government as Head of Technical Writing at the Government Digital Service (GDS). Having moved from government to finance, she recognizes she's drawn to creating inclusive and user-centred content in traditionally unfriendly industries. She likes using developer tools to manage docs, demystifying the writing process for engineers, mentoring junior writers, and presenting her adventures in documentation at conferences.