Jared Bhatti

Aligns the craft of writing with the craft of programming

Contains easy-to-follow processes, templates, and best practices for creating, organizing, and maintaining documentation

Written by experienced writers and developers from Google, The Linux Foundation, Stripe, LaunchDarkly, and Monzo,

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

6. Designing documentation

1. Defining your initial set of content

2. Deciding your minimum viable documentation

3. Drafting test and acceptance criteria

7. Understanding content types

8. Concepts, tutorials and reference documentation

9. Code comments

10. API specifications

READMEs

11. Guides

12. Release notes

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

14. Mechanics

15. Headings

16. Paragraphs

17. Lists

Notes and warnings

18. Conclusions/tests

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

20. Gathering initial feedback

21. Feedback methods

22. Integrating feedback

23. Getting feedback from difficult contributors

Editing content for publication

1. Determine destination

2. Editing tools (Grammarly, linters, etc)

3. Declaring good enough

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

25. Designing your information architecture

1. Content information architecture styles

2. Designing for search

3. Creating clear, well-lit paths through content

26. User testing and maintenance

27. Planning for document automation

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

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

30. Measuring documentation success

31. How documentation succeeds

32. Measuring different types of documentation quality

1. Structural Quality

2. Functional Quality

3. Process Quality

33. Measuring what you want to change

Drawing conclusions from document metrics

34. Working with contributors

35. Defining how decisions are made

1. Deciding on a governance structure

2. Writing an effective Code of Conduct

36. Choosing a content licence

1. Code licenses

2. Content licences

Building and enforcing a style guide

37. Editing submitted content and giving feedback

38. Setting acceptability criteria

39. Editing for accessibility and inclusion

40. Editing for internationalization and translation

41. Giving actionable feedback

42. Planning and running a document sprint

43. Maintaining documentation

44. Creating a content review processes

1. Assigning document owners

2. Performing freshness checks on content

Responding to documentation issues

1. Separating documentation issues from product issues

2. Responding to users

45. Automating document maintenance

1. Automating API and reference content

2. Using doc linters

46. Deleting and archiving content

47. Wrapping up