In the latest "Software Development magazine's Agile Modeling newsletter" (don't have the first clue when/why/if I signed up for this email, but it's been interesting so far and I haven't starting trashing yet), Scott Ambert talks about when to and when not to document, using "Agile Modelling" as his context.

Here's what "Agile Modelling" is in brief, taken from his site:

Agile Modeling (AM) is a practice-based methodology for effective modeling and documentation of software-based systems. Simply put, Agile Modeling (AM) is a collection of values, principles, and practices for modeling software that can be applied on a software development project in an effective and light-weight manner.

I'd like to look at three of his points, the first a "when to document" and the next two are "when not to document" (bold is mine):

[A "when to document"]:
--To support communication with an external group.
It isn't always possible to colocate a development team, and it isn't always possible to have project stakeholders available at all times. When you need to work with an external group of people, you need to find ways to communicate with them. Shared documentation is often part of the solution -- along with occasional face-to-face discussions, teleconferencing, e-mail and collaborative tools -- but it should play only a supporting role. Documentation should be a last resort for communicating with an external group, because it's far too easy to misunderstand something that's been written.

[Two examples of "when to not document"]:
-- Your process says to create the document.
Although this isn't a problem with agile software processes, it can be with prescriptive processes.

-- You're specifying work for an internal group.
Documentation is one way to communicate, but it isn't the best. Instead, consider working sessions with the other group or the use of collaborative tools.

Let me clue in the ill-informed: You're always programming for the guy/gal who's going to replace you. Likely you don't who know this person is going to be. You can't assume they're already in your working group. You have to write code that "passes the bus test" ("in case you get hit by a bus tomorrow") -- or, as I like to phrase it, pass the less violent "techno-hermit test" ("in case you go all ludophobic and run for the hills without your laptop tomorrow"). Chances are after any programmer turns in their notice, those two weeks or so won't leave enough time to find a replacement and adequately effect a knowledge transfer. Nor is it very useful to shove the knowledge into an intermediary. It's best to have the code have docs with it as it's being created so that a new schmoe can get that knowledge without the original hacker there -- and it also has a near-magical effect of creating better code as well.

(Aside: I'm not asking for mad docs. You should have exactly as much documentation as necessary for a programmer with equal skills to pick up and understand what's going on in a general sense without looking at the code. This could very well mean just a collection of well written flowerboxes to objects and methods, but could be something a bit nicer, with pix of the interface, etc.)

Although the belief that programmers can be thought of as inhuman, interchangable resources, which is obviously not the case, is too widely held, the best programmers and programming groups do their best to deliver high-quality code and documentation that makes the impossibliity of having interchangable programmers as nearly the case as possible.

So let's sum up. You're always programming for an external group, meaning that documentation can safely -- and should! -- be part of your process. Nothing, and I mean nothing, hurts a project like a developer leaving and the new fellow or gal coming to work on a cyborg with the human-half missing. Except for hiring boneheaded coders in the first (or second) place.

Labels: