Write the Docs: David Hooker – What I have taught developers about writing

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

David wrapped up day one of the conference. He works as the writer at Prezi and handles the knowledge base, the engineering blog, and pretty much anything you see with words and Prezi.

In some way, shape, or form communication can let us down. A belief in documentation is a belief that communication can be improved through writing. You’ve created something you’re proud of and you want to share it with the world so that they use it.

The best way to engage someone’s interest is to hook on to emotion. Your words are what allow you to do that.

David outlined 4 rules for drawing upon someone’s emotions:

  1. Start with the good shit. Don’t start with the backstory, start with what’s interesting.
  2. Keep it simple. There’s lots of places where complex writing can go wrong.
  3. Write what people actually say. Usage trumps any of the rules; formal language rules are just that, formal.
  4. Don’t repeat. Repetition in speech sounds great, but the eye doesn’t like it.

You can choose to make your writing exciting. No one needs to be able to tell that an engineer wrote your documentation.