Tuesday, July 05, 2005

Methodologies and Documentation Standards

Alistair Cockburn discusses Characterizing People as Non-Linear, First-Order Components in Software Development in this article.  He makes an important point on the impact documentation requirements/constraints can have on the success of a project.

I find that most projects run just fine on (accurate) low-precision descriptions: low-precision project plans are easier to read, adjust, and negotiate.  Low-precision architecture diagrams are easier to remember, low precision requirements tables are easier to prioritize and evaluate early in a project, low-precision design documentation is better at giving the reader "the idea" of the design - and then letting them look around.

Low precision artifacts use the strengths of people to lower development costs.  They draw on "good at looking around" and face-to-face communication, while forgiving inconsistency of update...

This observation matches my experience in the field - a few years ago my manager at the time and I came up with the concept of the Memorandum of Understanding (MOU for short).  This is basically a simple memo with no constraints on the content.  Content is dictated by the project it is written for.  Written in broad brush statements it is equally suitable for reading by the client and the developer.  We trust our developers to fill the gaps in the document/design by applying standardised techniques.  Does this cause maintenance issues?  Not really, as Alistair states:

I ask maintenance people how they manage to make program updates, in the face of out-of-date documentation.  Their answer is that they "just look around", they don't trust the documentation in any case - they just read the code...

And that's all we do - at the pointy end the code is the most accurate documentation.

1 comment:

LaraCroft said...

And it's a living document, so you can, as a developer, add to it later any notes that you think someone doing updates will need to know. But you are right that when updating/maintaining other people's work it helps to have the broad scope via the MOU, details in workpacket and maybe previous workpackets, and then one looks at the code for the details. Although for people like me, the dev code is the only version I can see, not the production/testing - so it is important that these be kept the same, or where they aren't (removing an email address on dev for testing without spamming for example) a comment in the code needs to be made. If code is to be the ultimate documentation, it has to be consistent.