Harness the Real Power of Documenting

One of the tenets of agile software development is to avoid needless documentation. That is, if documentation doesn’t provide value, don’t do it: writing documentation for documentation’s sake is a waste of time.

That’s because it is common to waste a lot of time preparing low-level, detailed design documents that become obsolete almost immediately. Worse, these sorts of documents generally have no audience—they aren’t serving any useful purpose, other than fulfilling a checkbox to prove that the team “produced documentation.” Because it’s such a wasteful practice, agile teams take a hard look at any documentation they are required to produce to ensure that there’s a genuine need for it.

Many people interpret this as “agile developers don’t do documentation,” which is wrong. Agile developers do create documentation, but they use a pragmatic filter to make sure the investment in creating any documentation is really worth the effort. It has to have value.

That brings us round to this idea: what’s the value in producing documentation to the writer? Producing low-level design documents that simply mirror the code (and become obsolete almost immediately) don’t provide any value to anyone. But other forms of writing documentation may prove valuable, even if there is no obvious audience for it.

Chance favors the prepared mind.

Louis Pasteur once said, “Chance favors only the prepared mind,” and functional MRIs and EEG tests are proving him correct. A recent study^[114] suggests that mental preparation that involves an inward focus of attention can promote flashes of insight, even if the preparation occurs well in advance of facing any particular problem.

Turning your attention inward, as you would do when working with a mind map, sets up some condition in the brain that allows for happy flashes of insight later in the project. So, it might be that documenting is more important than documentation.

Reader and pilot Derek Wade sent me the following related story:

I noticed this phenomenon when preparing for an aerobatic routine. Sequences of aerobatic maneuvers are often preplanned and diagrammed using Aresti notation before being flown. During the flight, we should pretty much have the sequence memorized, but having a card taped up in the cockpit with the sequence drawn on it helps during brain farts.

There are Visio add-ins that allow people to create very nice-looking Aresti cards, but I prefer to hand-draw mine, in an almost ritualistic way. I sat down to do so at the airport one day, and the owner of the school nudged another student, pointed to me, and said, “Watch this, this is cool.” I had no idea why she thought so. I thought I was just drawing out my card and taking too dang much time about it.

But apparently I was also “preparing the mind.”

➤ Derek Wade

As I mentioned earlier (in ​Visualize Insight with Mind Maps​), taking notes seems to be very important, even if you never read them again. In Derek’s case, there may be several elements at work:

• Hand-drawing the cards emphasizes R-mode processes.

• The active creation of the notes/cards helps prepare the mind for the later activity.

• Visualizing the sequences and maneuvers can help “groove” the mind (we’ll talk more about this shortly in ​Imagination Overrides Senses​).

You don’t have to use index cards or even real paper; the back of the napkin is just fine or maybe a large whiteboard.

Or perhaps you might want to take an hour to create a podcast or screencast. You may find that’s more productive for yourself and more engaging for the consumer of the information. It’s also probably cheaper than taking a week (and a committee) to produce a lengthy document.

Make a screencast.

Screencasts are really useful to convey something dynamic: showing a user how to perform a task using your software or modeling the life cycle of an object through a complicated set of processes. It’s a cheap and cheerful way to have lots of people (or remote people) look over your shoulder to see what you’re talking about.

Just think of it as another way of teaching yourself the subject. Of course, another powerful learning technique lies in teaching others.