Comments on: On documentation (or lack thereof)

By: Avoid formal specifications « Simpler is better

Avoid formal specifications « Simpler is better — Tue, 24 Feb 2009 10:44:04 +0000

[...] 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 [...]

By: David J Carne

David J Carne — Tue, 04 Nov 2008 21:05:10 +0000

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

By: Simon Pascal Klein

Simon Pascal Klein — Wed, 09 Jul 2008 12:52:22 +0000

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.

By: Matt Balara

Matt Balara — Sun, 06 Jul 2008 22:15:06 +0000

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.

By: Leisa Reichelt

Leisa Reichelt — Sat, 05 Jul 2008 10:37:36 +0000

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.

By: Gordon

Gordon — Sat, 05 Jul 2008 10:30:19 +0000

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).

By: Nathan Bowers

Nathan Bowers — Fri, 04 Jul 2008 00:57:29 +0000

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.

By: maya

maya — Wed, 02 Jul 2008 17:57:42 +0000

> 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 :))

By: Lee McIvor

Lee McIvor — Mon, 30 Jun 2008 09:20:59 +0000

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”….

By: Grant

Grant — Thu, 26 Jun 2008 23:46:21 +0000

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.