Writing So Your Words Are Read
summary
Claim: readers are not you, so documentation succeeds when it shows concrete steps, scaffolds missing knowledge, and makes tasks feel possible. Practical techniques include step‑by‑step install with virtualenv and file names, linked terms (composer, Requests, urllib3), monospaced and colorized code blocks, screenshots and GIFs, and gender‑neutral wording. Examples cited: Django REST framework QuickStart, Stripe copy‑paste demo, Fabric and Requests docs. Built outcomes include a self‑taught Python/Django site turned startup and two self‑published books, both used to validate these methods.
AI-written summary · about
chapters (23)
- 0:00Start
- 3:11Better documentation = More users. Less support requests. More contributors.
- 4:21How do we make our content, technical writing, and documentation easy to read and enjoyable?
- 4:32Creating friendly and welcoming writing. (Let's throw some best practices out the window)
- 6:17Write like a human, not a machine.
- 8:31Try personas - create a character and write for them.
- 8:41What would Fred (a designer working on his first programming project) need to know?
- 11:04Link anything that you don't want to explain.
- 11:49To get someone started with your project: teach- don't tell.
- 13:27Dumb things down (without making them dumb.)
- 15:34Use gender-neutral language.
- 17:141. Take a break.
- 17:42The basics of writing clearly.
- 18:06Break into bullets and use lots of headers. Make it easy to skim.
- 18:26Use italics and bolding to break up paragraphs.
- 19:23Don't forget your headlines.
- 20:00Simplify your language. Is there a more direct way to write the same thing?
- 20:48Mark up your code snippets to make sure they're styled differently.
- 21:42Add filenames to code blocks if it makes sense.
- 22:22Document with pictures.
- 23:35Remember that your readers have different backgrounds and experiences than you.
- 24:09Be friendly and write like a human.
- 24:23Simplify. (applies to length, word choice and complexity, layout, everything.)
related talks
51mWriting the Darn Docs
49mExplain Yourself! Documentation for Better Code
37mHumanising Your Documentation
34mHumanizing Your Documentation
01h 14mTechnically speaking: Improve Your Code With Documentation
40mHow to Write Documentation for People That Don't Read
06mHumanizing Your Documentation
26mWhat Writing Dictionaries Taught Me about Writing Documentation