Daniel Harrison's Personal Blog

Personal blog for daniel harrison

The CookBook Approach To Making Up For Missing Documentation February 26, 2008

Filed under: development — danielharrison @ 4:34 pm

The last bunch of people working on the code were a bunch of crack smoking monkeys. It’s landed in your lap like a wet cat and it’s your job to pull it all together, make it work and ship it yesterday. The entire documentation for the project is a patchy user manual and the people responsible who know what it’s supposed to do have moved on after being told that maybe they’d be more suited to something like, well, knitting or demolition.

I’m going to detail a strategy that I’ve used a couple of times now successfully to help fill in the cracks. I figured it’s probably worth writing up so I remember it and can point it out anonymously. Look, it’s on the internet, it must be authoritative. It won’t give you pristine documentation but I’ve found at least, it will give you a basis to build on for the next few releases. If you’ve got nothing and you can’t stop and write it all up (who can?) you’re not going to be able to fix it all in a single release. You can plan to fill it in though and see the light at the end of the tunnel. First of all you’ve got a project wiki right? Something you and the team can write informal documentation on? If you haven’t go download and install somewhere, and come back later. Ok so on to the story.

My grandma had a cookbook. It wasn’t a hard cover printed manual with a picture of an attractive (or not so attractive) chef gracing the cover. It was a behemoth. It had escaped the binder that contained it. It had devoured other cookbooks. When my grandmother had particularly liked something she had liberated it from it’s uniformity in a published cookbook, ripped it out and crammed it in there. There were handwritten recipes in an unfamiliar hand that I’m sure she had brought from distant ancestors. It had food stains on it. Maybe she thought if you couldn’t read it any more at least the food stains would give an indication of the ingredients. An early form of scratch and sniff maybe? Here’s the rub though, it was disorganised and in a lot of case incomplete but she knew it back to front and in between. Based on her knowledge of the world she could use it to build on and serve consistently high quality meals. When someone at dinner said ‘I must get the recipe for this’. She would know exactly where the recipe was, she’d take it out, rewrite it filling in all the skipped steps and then someone else could make something great.

So nice story? but how does this relate to code and documentation? I’m going to suggest you start building a cookbook. This is where the wiki comes in. A cookbook isn’t complete. It doesn’t contain the thousands of variations on macaroni and cheese, but it does usually have a single recipe which captures the intent.

So in this context, what’s a recipe. Well the way I’ve thought about it is a recipe in a application context usually covers a simple functional area. Eg employee mangement. It will have a UI usually for creating, editing, deleting and updating. So it has a datasource which in most cases is hooked up to a db and may encompass a database and maybe some stored procedures. There’s probably some data integrity constraints or some interesting behaviour. It may be related to another recipe, eg organisation hierarchy. It may have some gotchas, deleting a employee only sets an additional field indicating they’re no longer active but doesn’t actually delete them. There’s no hard and fast rule but you need to come up with something people can add to and build on so that you can start filling in what the system does. I usually create a really simple template.

  • Functional Area Description – what does it do, who uses it, when do they use it
  • UI – Basic sequence, create with this form, delete with this form, this validation sequence is important
  • Data – These are the tables that are involved, this uses this specific algorithm
  • Gotchas – General things that might trip someone up. The worse the code the more important this is.

For a first release 50-80% coverage is good. You start to build an understanding of the system. Future specifications actually have a basis and documenters, testers, developers can start adding and reading it. You get a bit more time on the next release because some of it’s already documented and you’re not starting from scratch. You start organising it into categories and breaking it down a bit more. You start adding things like schema diagrams, system UML sequences and data integrity documentation, glossaries, table of contents. Eventually you end up with pretty good documentation. I ‘ve found that development actually gets faster, when someone asks or someone new joins the answer is, it’s on the wiki in the cookbook.

This is a strategy I’ve found helpful, it’s not perfect but it’s often a good start and a good conversation a team can have with familiar concepts.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s