Writing

• A list of fictitious numbers, domains, and more

  Avoid using real credit cards, phone numbers, IP addresses, domains, and postal codes with this list.

  6 December 2021

• Don’t blur screenshots if you want to keep your secrets

  Blurring isn't the the way to protect personal information.

  18 November 2021

• Better-than-Grep tools for writers and developers alike

  Searching docs-as-code files doesn’t have to be slow and frustrating.

  21 September 2021

• 4 ways to keep PDF docs off Google search results

  If you’re stuck serving PDF docs, consider these ways to improve search results.

  9 August 2021

• What does “deprecated” mean to your readers?

  When a feature is on its way out, the terminology doesn’t matter.

  21 July 2021

• When is it safe to use “new” in technical documentation?

  Some tech writers say never write “new”, but it’s safe to use if you understand its power.

  16 June 2021

• Git reflogs don't have to be scary

  Git gives you lots of tools to escape bad situations. Why are they all so cryptic?

  10 June 2021

• 4 ways to keep distractions out of your screenshots

  Sick of contorting to keep irrelevant elements out screenshots? Here are four tips to help.

  3 June 2021

• Should you use the first-person plural in your documentation?

  Most style guides say that, no, we're not in this together after all.

  6 May 2021

• What do you say to “no one reads the docs”?

  You need a way to respond with confidence that creates an opening for real understanding.

  15 April 2021

• The second person is OK in developer documentation (but don’t take my word for it)

  Style guides are unanimous on this one thing.

  17 March 2021

• Three ways product and feature names get mixed up in your writing

  Names change, become forgotten, or never were. How do you keep your content consistent?

  19 November 2020

• Scheduling content with static site generators and automatic deployments

  There are lots of ways to schedule future content with a static site generator. Here’s how I do it with GitHub Actions and Netlify.

  29 July 2020

• Felt trite might delete later: the hows and whys of avoiding clichés

  Some ideas to help you avoid clichés in your business or technical writing.

  17 June 2020

• How small is too small to launch new docs?

  How much is enough to launch? A question that haunts writers when there are no external deadlines.

  6 May 2020

• Think habitat, not ecosystem, when you choose a static site generator

  If a static site generator’s ecosystem is an ocean, then you might join a happy school of fish or become chum for the sharks. Think about your niche before diving in.

  22 April 2020

• When notes aren’t enough: how to record subject-matter experts

  Overcome the awkwardness and get permission to record your next meeting

  23 January 2020

• The 30-minute information rescue

  No follow up questions please: what to do when only get once chance to talk to a subject matter expert

  28 August 2019

• What's the difference between a function and method?

  An attempt at clearing up a common point of confusion.

  25 March 2019

• Acute Strategies

  I made a strange little productivity game inspired by the Pomodoro Technique, Brian Eno, and “Zen and the Art of Motorcycle Maintenance.”

  29 June 2018

• Pay the Docs: pay transparency at Write the Docs Portland

  How can people who write the docs understand their and their peers' compensation better? I moderated a discussion to find out.

  21 May 2018

• Checklists for public speaking

  Checklists are a great way to deal with nerves before public speaking.

  5 April 2018

• Meeting invitations for people who hate meetings

  Better meetings start with better meeting invitations.

  15 March 2018

• How I helped Mozilla turn documentation into data

  Mozilla asked me to work on an project: turn documentation into data. When is documentation better off as data?

  14 February 2018

• Stop excluding your audience

  Avoiding exclusionary language can keep your audience on your side.

  3 January 2013

• The Feedback Matrix

  I have a rubric for evaluating feedback on written content.

  29 November 2012

• Five reasons you need an editor

  Everyone's a critic, so don't make it easy for them to be critical.

  14 November 2012

• How to replace a Kindle 2 battery

  Give a Kindle 2 a new lease on life by replacing a degraded battery.

  17 October 2012

• Documentation is artificial experience

  The best documentation is a shortcut through time.

  10 October 2012

• Don’t be so negative

  Instructions with conditions be hard to write clearly. Here are a few tips to make them easier to understand.

  3 October 2012

• Writing feature requests and bug reports that get results

  You can make a strong case for bug reports and feature requests, if you get organized.

  19 September 2012

• Setting expectations in step-by-step directions

  Step-by-step directions work best when you give your reader a way to gauge success or failure.

  9 December 2010