On documentation (or lack thereof)

I was talking to someone recently about doing some work with them. They said ‘can you send me some examples of documentation you’ve done lately’ – they wanted this to check that I could do what I said I could. Fair enough. Except, aside from the fact that all the documentation I’ve done lately is commercially confidential, so I’d have to hack it around a little to be able to show it to someone else… it made me realise how long it’s been since I’ve actually done the kind of ‘finished’ documentation I used to spend a lot of my time doing.

I just don’t work that way anymore, it seems. Sure, I still do wireframes every now and then, but never a ‘complete set’ and often with no where near the detail I used to include. Why? I think there are three reasons. Firstly, I tend to work on more of a strategic level than a detail ‘exactly where does that button go’ level these days. Secondly, I tend to work on projects where there is no time for that level of detail. And finally – and most interesting I think – I tend to work closer to the production team these days – more often are graphic designers designing and/or developers developing the very same stuff I’m wireframing at the same time. Investing too much in the documentation is a waste of everyones time – much better to do just enough to get them going and then work collaboratively with the team to do the fine tuning.

Personally, I think I should have been working more like this since forever.

Does any of this sound familiar?

10 Responses to “On documentation (or lack thereof)”

  1. Grant June 27, 2008 at 12:46 am #

    I’m soooo hearing you on this one. I’ve noticed the same thing. And the few times I have to write detailed documentation nowadays, it always fails in it’s objectives.

    The only issue I have with the “incremental” or “just enough” documentation model is when the project is complete, and you need to revisit the project for some reason. It can be hard to work out exactly what was decided.

    I also find that some clients (and colleagues) find it difficult to keep track of all the various documents that need to be collated to present the consolidated picture of the project.

    All that said, I think the more “agile” approach works much better in practice, and is worth these few drawbacks for the benefits it provides.

  2. Lee McIvor June 30, 2008 at 10:20 am #

    I agree completely.

    I’m a big proponent of working directly with designers and developers as much as possible so that the need for such detailed documentation isn’t always there. It saves time and ensures that all parties feel properly involved in the project, instead of me dropping a pile of documents on them in one go.

    I can see benefits to substantive documentation in some organisations, and in larger projects it’s often important to document your decisions if for example you’re dealing with remote or offshore development teams, but if you can replace those x days of formalised documentation with faster, more agile methods and consultation with the rest of the project team, then that’s definitely more effective.

    The problem with all of this of course is that prospective clients still want to see nicely designed “deliverables”….

  3. maya July 2, 2008 at 6:57 pm #

    > Does any of this sound familiar?

    yes !!!

    > Personally, I think I should have been working more like this since forever.

    yes !!!

    (this is the blog post I have been wanting to write :))

  4. Nathan Bowers July 4, 2008 at 1:57 am #

    Documentation died for me at my last corporate web design consulting gig. The interview as all about what new awesomeness I could bring to the project, but then on day 1 they dropped a year old(!) 2″ thick spec/wireframe document (by an earlier long gone consultant) on me that I was to mindlessly implement.

    I vowed to never again be an “implementer” of someone else’s designs, and I vowed to keep my own documentation as simple as possible. Now I work with clients who want working products, not a pretty binder that takes months to assemble. I still wireframe, but quickly, in pencil, then I scan and email for concept approval. Much happier now.

  5. Gordon July 5, 2008 at 11:30 am #

    Sounds very much like you’ve moved from (in software development language) a waterfall model (lots of documentation, slow to move as you need to wait on it all down the ‘fall), to an agile development method (little to no documentation, short lists of ‘to do’ items and some whiteboarding. Constant communication is key).

  6. Leisa Reichelt July 5, 2008 at 11:37 am #

    yay, glad I’m not the only one :)

    Gordon – it does sound that way, doesn’t it… the funny thing is that hardly any of my clients would actually describe the way they’re working as ‘agile’, at least not formally.

    There is definitely a big shift going on though, in my experience.

  7. Matt Balara July 6, 2008 at 11:15 pm #

    Good, solid, piles of paper, which can be measured in centimeters and kilogramms, and *whumped* down on the table when anyone is silly enough to have a question just seem to be part of “the Enterpri$e” control mind-set. Although I’m sure there are plenty of business folks who’d be happy to accept less documentation if they understood how much it needlessly costs them.

    I was talking to Thomas Vander Wal at reboot10 (we missed you leisa!) about this. His docs at just a few pages. My interpretation is his approach is teaching, not chiseling in stone.

    Gives me some hope for my future after the agency, where we’re *always* forced to produce the paper piles.

  8. Simon Pascal Klein July 9, 2008 at 1:52 pm #

    Commercial confidentiality is a common issue, and has been used as a selling point for attracting developers in open source projects—developers (in particular students and newcomers to the field) can get involved in great projects, publish code and are free to promote themselves using this work. This model can easily be expanded to include non-programmers—open source projects could always use a few more talented documentation writers, artists (and UXD professionals!).

    Kudos for your talk at GUADEC.

  9. David J Carne November 4, 2008 at 10:05 pm #

    Yes I too agree entirely with you. People do tend to get bogged down with these things

Trackbacks/Pingbacks:

  1. Avoid formal specifications « Simpler is better - February 24, 2009

    [...] 29, 2008 · 1 Comment Leisa Reichelt’s post On documentation (or lack thereof) rang a lot of bells for me. Until my most recent engagement, it had been many years since I’d [...]

buy essay online