Wednesday, March 12, 2008

Writings should live

Why are most things I read on the job undead? Why are documents made in software companies like zombies?

zombie kids

Too often, they are born premature, they live quickly, then are dead before you know it. And not given a proper burial, they wander around, in our electronic halls of e-mail inboxes and obsolete web pages, looking for brains.

How else can I describe reading one of these things? You stare at the document, and usually

  • Some things are detailed, but don't really seem part of anything
  • Some things are vague, but stated as if they are obvious to everybody
  • Some things are obsolete

As you read it, half of your attention span turns to answering questions rather than learning material. These questions are often important, like

  • What does this mean?
  • Wait, didn't we agree to remove this feature 3 weeks ago?
  • How important is it to have our widget be resistant to power failures if the user can simply break it by uploading the wrong file?

There are many problems here. Bad writing. Bad publication. Bad. Bad. Bad.

Easy things to help avoid document zombiefication

Send links, not attachments. Host the latest version of a document somewhere. Then people should just always just jump to the latest rather than having to search their inbox.

Yeah, you can keep old ones around for posterity. But 9 times out of 10 you just need the latest version of whatever.

Write with meaning. When a concept is vague, make sure it sounds vague in writing. When it is not, use strong terms. A vague phrase: "it probably provides 10 feeds". An exact phrase: "it will provide 10 feeds".

This helps scheduling in a planning document. Vague things should be investigated before being done. Exact things can be put off.

Version with a date. There is absolutely no reason why your document shouldn't come with a date. You can use revision control systems, but I tend to find dates more universal, and easy to understand. Fancy numbering and variation schemes tend to muddy the water.

I have never, ever, solved a documentation problem by saying "what was the difference between version 3 and 4 of this document"? Instead, I think, "what changed the last 2 weeks"?

Think like a journalist. Most technical documents would be far better if they started with the big important stuff and then weaved in details later.

It's about context with your details. You need to know the why, not just the what. The who, the when, and the where are often not as interesting in software, but it can be.

No comments: