Tuesday, July 27, 2010

We must hate trees a lot..

Why must every document I see start with at least 3 pages that are completely useless? Most of them manage at least 6, and I've seen up to 20.

Sometimes I just want to take these docs, scroll through until I find the first statement someone could reasonably disagree with, and just delete everything before this point. I don’t think anyone would miss it except for some putz who will insist it all the goes back in on the ground that it's "standard".

This useless filler generally consists of:
  • Title page. Generally containing no more content than is available in the document headers and footers anyway.

  • Distribution and sign-off page. This never contains any record of actual sign-off, the distribution lists is always out of date. Old emails will always be used to substantiate the real distribution in any case.

  • Version history. This is either so terse it’s useless, or so involved it takes three pages. It is never used by anyone; again the email trail is used as the de-facto history. Maybe if you document control system supports version that could be used.

  • Glossary and Abbreviation. A list of items that are either so obvious that all reader’s will understand and know them already, Acronyms so obscure that even spelling them out helps no one, or items explained in-depth inside the document anyway. No one will ever read or use this.

  • Document Purpose/Audience/etc. A whole bunch of explanation about what the document is meant to do and for whom. Arguably defensible for a “one-off” type of document; but for a standard template that you use again and again does the audience really need reminding that the purpose of a business case is to secure funding? It’s either things readers already know, or if they don’t know it they need more education than you can fit into the document intro.

  • Project scope/benefits/overview/context/etc. A whole bunch of generic description of the project that’s repeated (in slightly different wording) in every single document. In the best case scenario readers will just skip this; in the worst it will be different between documents causing confusion.

    What’s the end result? 40 page documents where content that really matters doesn’t start until page 10. I’ve personally produced mounds of documents that are over %75 filler. This increases the cost of producing documentation, slows down review, and damages document readability. You can see why the whole idea of documenting an IT project is under attack.

    What’s really galling is that this document bloat doesn’t come from business customers demanding more – the pressure is from inside the IT. Look at a memo, or a board paper. You’re lucky if there are more than a few centimetres of document meta-information at the top. A paper going to the board to recommend a few million dollars of spend fits on a single A4 sheet; but the smallest IT document we manage to make as long as war and peace, but with as much content as a limerick.


  • Manage meta-info (versions, approvals, distributions, etc) in the same system that manages your documents. If your system can’t support that and you really think you need it (unlikely) then at least move it into an appendix.
  • Remove purely aesthetic cover pages, unless you’re writing a book it’s just getting in the way.
  • Centralise repeated information in a living document. The project scope and overview document should be the only place that summarises repeated general project information. Put all the effort of re-drafting, re-reviewing, and re-writing the same content in every document into keeping it up to date instead. If you really have to reference it at the start of the document, if you really, really have to then copy and paste it with a explicit statement about where it was copied from.
  • Do what I said at the start of this post. Start at the top of the document, scroll down until you find the first statement someone could reasonably disagree with, and just delete everything before this point.
  • Thursday, July 22, 2010

    Kick-Start Templates

    If you were ever looking for a basic set of documents for your SDLC it's hard to go past these:


    It's no surprise they're excellent as they from from Karl Wieger's consulting company, and he did (literally) write the book on software requirements.