We can all agree the world is under-documented. However, some of the documentation that currently exists, shouldn't, and it trains users to ignore the other docs we've spent so much time crafting.

We'll talk about common documentation traps, including autogenerated text and poka-yoke replacements, and how to recognize and purge them in your own projects to create a better user experience.

1. Introduction
   1. Me
   2. iFixit/Dozuki/tech writing program/HBR article
2. About the title
   1. Good documentation's worst enemy is bad documentation
3. "Documentation sucks"
   1. Bug in software, we might say "never use this software" (ImageMagick)
   2. Bug in documentation, we say "never use any documentation"
   3. In general, we're all numb to documentation - we don't read it because we expect it to be bad.
      1. Sometimes this bites us in the butt - my magnet-powered flashlight.
   4. Broken window syndrome. Bad docs beget bad docs.
4. (Aside) Outdated docs
   1. How do we solve this? Pre-merge documentation update requirement
   2. Code + docs + tests + metrics + alerts
5. Auto-generated docs
   1. Laziness, impatience, hubris.
   2. Laziness leads to computers writing documentation, which sucks.
   3. Humans read your docs, so humans need to write them.
6. Overly-verbose instructions.
   1. Omit needless words.
   2. Know your audience - don't write super-introductory text for experienced users.
7. Poka-yoke replacements.
   1. git-scripts feature/hotfix merge