03.21.08
Document reuse
I think everybody agrees that reuse is a good idea generally. Reusing
glass jam jars is vastly more efficient that recycling them into new
jars. Reusable templates are much more efficient that drawing the
damned thing ever time. Reusing code libraries is the only way the
majority of programs could ever be created. There are however limits.
When reviewing documentation of formal processes, be that performance
testing approaches, or client bids, or upgrade instructions it is
obvious many of them are reused from other projects. His is not a bad
thing, after all if you had to recreate these from scratch every time,
you’d spend three quarters of it re-inventing the wheel, re-finding the
things which caused you problems last time, but reused and reworked
documents have some major problems, the majority of which appear because
the document is a reused, recycled, reworked and reissued version of a
document which has been reused, recycled, reworked and reissued which
is a.. you get the message. Like a copy of a copy of a VHS tape, each
re-iteration introduces problems, not removes them.
Each iteration introduces document creep. Things are not removed
because “they were there already, and it must be for a reason, so we’ll
need one too” rather than being thought about logically. Each project
has it’s own quirks and just because a previous project manager wanted a
break down of the risk profile in it (because they understood that area
and wanted to feel like they were really adding some solid content)
doesn’t mean your document needs on necessarily.
Joel On Software has an excellent article about this explaining that
ever Microsoft document had an Internet section, because one of them
once did (cant find the damned link!). As well as not removing things, everybody adds something.
This is because otherwise they don’t feel like they’ve bought into this
document, it’s not really theirs until they’ve added the section about
refactoring SQL to run more efficiently, or the best method for counting
the spiders using toothpicks, or whatever their specialist subject is,
and thus the document gets a little bit bigger and a little bit less
manageable.
The other thing that people never ever want to remove, are the reviewers
and people who need to sign a document off. Often these people are very
senior, and really, honestly, they are not going to read it, so they get
somebody who works for them to be on the list as well and so on and so
forth. Nobody will ever remove a reviewer or signee (I’m not sure this
is a real word), for fear of the “Why the hell didn’t I see this
before!” conversation that will take place if something goes wrong. The
problem with this is too fold.
Firstly, it gets to be virtually impossible to get the documents
reviewed and signed off, because all 20 people who review it won’t
finish it on time, and then once you finally work in the 87,746 changes
they suggest (20,341 of which will be the same) you’ll never get to 47
senior people on the list to sign it off. Why, because they’ve not read
it. Why have they not read it brings me onto the second reason why this
is bad.
Secondly, people end up completely swamped. With everybody producing
documents wanting everybody else to review it and sign it off, people
stop doing it. They delegate it if they can, or they skim read it and
miss the critical points. They are snowed under with stuff, the content
of which they are interested in 6% of. There’s a greats story about
NASA crashing a probe into Mars which was caused by one group working in
inches and the other in metric units. Somebody actually had an email
about this in their inbox, but they missed it because it was 40 feet
down.
So how do you get round this? What’s the solution? Here’s what I
recommend.
- Do re-use documentation. Get a big stack of examples, not just one, and slice them up into bits.
- Work out which bits you need. Go back to first principles if you have to (I always fall back to who, what, where, when, why and how).
- Write a framework. If you are having to juggle layouts to get things to fit neatly, you’ve probably got too much in there (see my post on implicit feedback loops in PowerPoint)
- Do not review by committee. Get individual sections reviewed by single people who understand that area. Get a peer to review it over all to make sure the individual bits hang together.
- Consult people before picking a way forward, if the review is the first time they see it they will go in cold and be surprised by everything they don’t understand,
- Have a single overall reviewer. They need to be the person that is going to have to do this stuff or be responsible for it.
- Have a single overall sign off person, they might then delegate it, but do not add their delegate to the list. If Jeff nominates Steve to review it on his behalf, Jeff will sign if Steve does. So why have both? If Steve isn’t senior enough to be seen to shoulder the responsibility, just have Jeff (who’ll still get Steve to read it). If Steve is senior enough, why bother with Jeff.
- Be vicious with what you write. A diagram can save hundreds of words, if it’s the right diagram.
- Don’t add content just because you feel you should. Include what is needed eg. The approach, the steps to do it, the justification and the timescales. You do not need to include, other than as a single line, all the other options you discarded.
- Put a summary at the beginning. Each section of the document should be summerisable into a couple sentences. Having this allows a super busy person to glace it and see the things that they needed to glean from the 40 pages of fine detail included later. A 150 line details plan can be turned into “Starting on 19 of May, finishing on 25th of May, 5 daily check points, each server being brought online one at a time, approximately 2 every day, and this will give enough information to point out that there is a strike on the 20th.
Who knows if this works, but once you’ve staggered through some of the 40 pages documents which say absolutely nothing, you’ll give anything a try.
