HackNot - Documentation

Oral Documentation: Not Worth the Paper it’s Written On¹

The Agile Manifesto² states:

“The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”

Forgive me for questioning a holy proclamation, but isn’t it rather well established that verbal communication is often incomplete and ambiguous, and that human memory is inaccurate and prone to confabulation? The plethora of psychological research in such areas as false memories, the veracity of eyewitness testimony, and the effect of predisposition on the interpretation of sensory data has surely given us a big hint that our perceptual and communicative capabilities are erratic and dubitable?

So where comes the apparently wide spread acceptance of (or at least, lack of challenge to) such outrageous Agile sophistry? For my part, it is difficult to ignore the manifest problems associated with a development team’s reliance upon face-to-face communication. Over the last 3 or 4 months, as the inheritor of a code base whose authors preferred the “verbal tradition” style of documentation, I suffer daily from the flow-on effects of this laziness. Let me illustrate by providing you with a summary of a typical day for me in recent months, so you too can marvel at the feel-good richness and super-duper efficiency of face to face communication amongst software developers.

Fade in.

Scene 1 - a cubicle. Ed is slouched in an office chair staring forlornly at the screen in front of him. Except for the occasional insouciant jab at his keyboard, he gives the appearance of being comatose.

The day begins with my desire to extend the functionality of a legacy application, approximately 600K lines of code. I need to locate that portion of the code responsible for performing function X, so that I can insert function Y just after it. I go looking for function X amongst the code. I can’t find it. In fact, I started looking for it sometime yesterday, and haven’t found it yet. I check the folder marked “docs”, to find it contains only a single README.txt file, the sole contents of which is the teaser “This directory will contain the docs” – apparently the dying message of a long extinct group of developers whose brains exploded before being able to make good on their promise. I find a piece of code that looks like it’s in the same ballpark as the code I’m looking for, and examine the revision history of the file it is in, to find that it has principally been developed by “Bob”. I must find Bob. I need to find Bob. Bob will know where function X is.

Here is my first problem. I cannot contact Bob directly, because I am but a lowly contractor. Bob is a valuable and in-demand member of my client’s staff, and I can’t just go up to him and steal his valuable time. There’s a chain of command to be observed here! I must lodge a request with my manager to see Bob, who will forward that request to a liaison officer, who will forward that request to Bob’s manager, who will then cue it up with Bob. If he’s not too busy.

Scene 2 - a meeting room. Ed sits opposite a brown-skinned man wearing a turban.

The next day, I get to meet Bob. He can only spare 15 minutes to talk to me, because he’s busy preparing for the next release of some whiz-bang new pile of crud. It’s at this point that I discover that Bob’s real name is “Sharmati Sanyuktananda”, but everyone just calls him “Bob” for short. Bob is Indian. Bob’s formal exposure to English was limited to the 15 minutes he spent reading “Miffy Learns English” while waiting in line at Immigration for his visa to be processed.

I try and talk with Bob, but it is like talking with Dr Seuss. At the end of 15 minutes, I have learnt almost nothing from him, and he keeps repeating something about public transport, which seems to have no relevance. His final word is “Sue”, who I know is another member of the client’s staff. So I contact my manager to organize some time with Sue.

Scene 3 - a meeting room. Ed sits opposite a nerdish looking woman wearing glasses with a very strong prescription.

Next day, I discover, to my significant relief, that Sue speaks English quite well. Unfortunately, her memory is a little hazy on the bit of code I’m asking her about. She remembers dealing with it about a year ago, but there’s been a lot of water under the bridge since then. At this point, I am beginning to consider tying weights around my feet and jumping off that bridge. She can’t tell me where functionality X is, but she’s pretty sure it isn’t where I’m looking. “Have you tried asking John?”, she queries. So I contact my manager and request a meeting with another client staff member, John.

Scene 4 - a meeting room. Ed sits opposite a cool dude with sideburns and shoulder length hair.

Next day, John is disarmingly candid about the code I’m dealing with. “Oh yeah, I remember this crap”, he begins. “We wrote that it in about a week, sometime last year, when we were up against the wall. It is absolute rubbish.” “No kidding”, I think. John is my guardian angel – he knows that function X got ripped out at the last moment, so they could meet their deadline. But then they put it back in a bit later, when things slowed down, and it’s kept in a different module in the version control system. Which one? “You’ll have to ask Declan”, says John in a matter of fact way. I ask my manager to queue up some time with Declan.

Scene 5 - a cubicle. Ed is slouched in an office chair, browsing the advertisements on an employment web site.

My manager replies a few hours later, saying that Declan left the company a few months ago – maybe someone else knows. Have I tried asking Bob?

Fade to black.

And that, ladies and gentlemen, is the delight of face-to-face communication amongst software developers. See how efficient and effective it is? No one wasted any time writing nasty old documents, which saved them a bit of time – once. Everyone since then has wasted the time they saved, multiplied tenfold, trying to recover the information the original author could have documented in an hour or two, but was too busy, choosing to rely instead on good old “face to face” communication.

When it comes to the maintenance and extension of legacy code, and clearing the organizational hurdles associated with the handover of code from one party to another, a reliance on “face to face” communication is very convenient for the first generation of developers, and a chain around the leg of every other developer and organization involved thereafter.

It all sounds very folksy and appealing when you just say the words. If you’re just talking in general terms about how much easier it is to have a bit of a chin wag with the bloke sitting next to you, then it sounds so reasonable to point out how much is being saved by just talking about stuff rather than writing it down. Of course! We’ll just have a little chat about it and everything will be alright. That same simplicity is a large part of its appeal to many developers. Unfortunately, reality is not quite so simple.

For a maintenance programmer, the reality of dealing with your predecessor’s reliance upon “oral documentation” is:

The people you need to talk to are often not available – their time may be spoken for, or they may have left the company.
The people that are available to talk with are often inarticulate techies with the verbal communication skills of a mime.
The people you talk to have fuzzy memories, particularly where low level details are concerned. Frequently, they simply can’t recall the information you need.
The people you talk to all give you a different account of how things work. You’re not getting the facts anymore, you’re getting opinions and best guesses.
The people you talk to have moved on to new duties and are not particularly interested in answering your queries about a system they would prefer to forget.

The “out” offered by XP/AM³ and other idealistic retreats is that you just “do the documentation as needed”. Brilliant! If only I’d thought of that, maybe I could’ve been a thought leader too! The problem is, “as needed” and “when time is available” are rarely coincident for reasons entirely beyond the developer’s control. Try and convince a manager that you need to take a week out to catch up on some documentation. During that week you won’t be writing code, you won’t be making any functional progress towards a measurable or billable outcome, but the schedule will be taking a hit. Good luck with that one.

Fowler has a few delightful stories of “handover” scenarios in which face-to-face communication has been achieved by paradropping an “ambassador” into an enemy territory full of maintenance programmers, so that knowledge can be still be transferred verbally, and documentation produced as required by those maintenance programmers. I would like to enunciate a question that has long been in my mind, but heretofore unexpressed: “Martin, what part of the Twilight Zone do you live in, and where can I get a ticket?” Really … is it just me or do the folksy anecdotes and one-off case studies that some Agile enthusiasts put forward sound just a little too contrived to be realistically transferred to your average corporate setting? Where are these companies they speak of, that have the latitude to abandon their normal procedures and protocols and set about bending over backwards in an effort to provide just the right climate to support these processes, no matter how involved the accommodation may be?

Whenever I read these fabulous accounts of the stunning success of AM/XP in some corporate environment, and how it didn’t really matter that the team prepared no documentation whatsoever, I feel like I’m reading some sort of fairy tale, where everybody finishes their projects without difficulty, and then goes off to have a picnic in some bucolic setting, where they eat cucumber sandwiches and drink lashings of ginger beer. Hurrah!

By contrast, here’s how handover happens in my world. One day – sometime before you’ve actually finished what you’re working on – some pointy-haired manager comes up to you and says “You’re changing to Project W tomorrow”. No thought, no discussion, no campfire chat and singing of old spirituals. Just the immediate transferal of resources from one emergency to the next emergency. Whatever difficulties you might leave behind – too bad. What happens to the programmers that come after you is of no immediate concern. This dooms the poor sods to spending inordinate amounts of time, as I have recently, wandering the halls like a restless spirit, shuffling from one vague and apathetic source of information to the next.

The reliance upon face-to-face communication that the XP/AM contingent favor is not the straighttalking, light-weight, near-telepathic communicative fantasy of the Agile dream, but a prescription for pain and suffering for every maintenance programmer that has to come along and clean up after the original programming team has done a hitand-run on the code base.

Are my experiences unique here, or do others find this whole “fireside chat” model of developer communication a little hard to swallow?

FUDD: Fear, Uncertainty, Doubt and Design Documentation⁴

“Think twice, cut once” – Carpenter’s adage

In the years that I’ve been doing software development, the one source of recurring dispute between myself and colleagues is the issue of design documentation. I am of the opinion that the production and review of design documentation significantly increases the chances of producing quality software, and that such documentation should be an integral part of the development of any piece of commercial software.

In the course of advancing this argument, I believe I have heard every counter-argument known to man (or “excuses,” as I prefer to call them). It would require a small book to document them thoroughly, in all their variation and inventiveness, but the following list covers the main ones:

We have a tight schedule and the sooner I begin coding, the better.
The document will quickly drift out of synch with the code.
I can always produce a design document later, if I have to.
No one looks at design documents anyway.
The information you capture can be obtained directly from the code.
I’m paid to write software, not technical documents.
The customer wants working software, not documents.
Nobody does Big Design Up Front anymore.
Never had to do it on any of my previous projects.
Everyone on the team knows how the system is designed.
A good design will emerge once we begin coding.
It’s better just to write the code, then recover the design later with a CASE tool.
I comment the source code thoroughly.
You can’t really understand how the software will work until you write the code.

I’m not going to try and disprove any of these statements. The state of empirical research in the area and the vagueness of many of the statements themselves forbids disproof. Additionally, it is quite possible to develop and deliver software without a shred of design documentation. Indeed, it is common practice.

But I believe that we can do better with design documentation than without it. In other terms, though a tradesman might achieve his end with blunt tools, the going is harder and the result messier than if he had used sharp tools. My experience suggests that design documentation is a sharp tool that we blunt with our own misconceptions and false beliefs about the role it plays in the development process. Given that I can’t prove that to you, I will try and persuade you of it by challenging some of the beliefs underlying the above statements.

It should first be acknowledged that for many developers, the notion of writing documentation of any type is a task they anticipate with the same distaste as root canal work. In other words, any of the above stated reasons for eschewing design documentation may really just be an attempt to rationalize the real reason:

I hate writing documentation.

I believe the enmity toward documentation that we see so much of in the development community derives largely from the cognitive shortcomings (real or perceived) of the average software developer. Many developers come from mathematics, science and engineering backgrounds, and talent in those areas is often accompanied by a proportional lack of ability in the humanities. Documentation requires expression in natural language, and a disturbing number of developers have approximately the same facility with the written word as a high school junior. Nobody enjoys doing things that they’re no good at. It’s frustrating and tiring.

From the reasons given above, I have tried to distill the core underlying beliefs.

Well written/commented code substitutes for design documentation
The team already knows the design, so there’s no need to document it
Code is the only meaningful work product and sign of progress
The maintenance cost of design documentation is prohibitively high

Let me challenge each of these beliefs in turn.

Well Written/Commented Code Substitutes For Design Documentation

Design documentation can provide value before the code is even written.

Senior technical staff frequently maintain an architecture-level view of the system being developed, leaving front-line developers to focus on whatever functional area they are currently preoccupied with. These are two distinctly different mindsets, and switching back and forth between them is tiring. When you’ve got your head buried in a complex multi-threading problem, you’re not inclined to be thinking about how your code fits into the overall scheme of things. Similarly, when you’re sorting out architectural issues, you’re not concerned with lower level implementation details. By having the design of a low level subsystem reviewed by someone with a high level view of system structure, we can ensure that individual units of work go together in an architecturally consistent manner.

Additionally, the very act of externalizing a design to a level of detail that convinces a reviewer that it is sufficient, can lead the developer to discover aspects of the problem they might otherwise gloss over in their haste to begin coding. The problem with “back of the envelope” designs and hastily scribbled whiteboard designs is that they make it easy to overlook small but problematic details.

The Team Already Knows The Design, So There’s No Need To Document It

Those who have taken part in the construction of a system have had the opportunity to witness the evolution of its design and absorb it in a piecemeal fashion over a period of time. But new team members and maintainers are thrown in at the deep end and confronted with the daunting task of gaining sufficient familiarity with an unknown body of code to enable them to fix and enhance it. For these developers, design documentation is a blessing. It enables them to quickly acquire an abstract understanding of a body of code, without having to tediously recover that information from the code itself. They can come up to speed with greater ease and more quickly than they might without the guidance of the design documentation.

Code Is The Only Meaningful Work Product And Sign Of Progress

This statement is true if the only lifecycle activity you recognize is coding, and the only goal towards which you proceed is “code complete.” As a design matures and different aspects of the solution space are explored, the designers’ understanding of the problem deepens. This progress in understanding is real progress towards a solution, even though it is not captured in code. The exploration and evaluation of design alternatives is also real progress, the end result of which is captured in a design document.

The Maintenance Cost Of Design Documentation Is Prohibitively High

Many developers view design documentation as a programmatic after-thought; something that you do after the real work of writing code is done, perhaps to satisfy a bureaucrat and create a paper trail. Any type of documentation produced in such a desultory fashion and out of a sense of obligation is likely to be low in quality, and of little use. So the preconception becomes a self-fulfilling prophecy.

It’s not difficult at all to create useful design documentation, as long as you know what use you’re going to put it to. I’ve found that useful design documentation can be achieved by following these two simple guidelines:

Include only those details that have explanatory power. There’s no need to put every class on a class diagram, or to include every method and attribute. Only include the most significant classes, and only those features that are critical to the class’s primary responsibilities; generally, these are the public features. Omit method arguments if you can get away with it. In other words, seek minimal sufficiency. This also makes the resulting document more robust to change.
Focus on dynamic behavior, not static structure. If possible, restrict yourself to a single class diagram per subsystem. Associations and inheritance hierarchies are relatively easy to recover from source code, but the interactions that occur in order to fulfill a subsystem’s main responsibilities are much harder to identify from the code alone. This is why reverse engineering of interactivity diagrams by CASE tools is ubiquitously done poorly. The primary function of the design document is to explain how the classes interact in order to achieve the most important pieces of functionality

That code can be written in such a way as to obviate the need for documentation is a retort of the documentation-averse that I’ve been hearing for many years. Those not keen on commenting their code will appeal to the notion of “self-commenting code”. Those not keen on design documentation will claim “the code is the design”. This phrase, as it is commonly used, is intended to convey the idea that the code is the only manifestation/representation of the software’s design that can be guaranteed to be accurate. While a design document will drift out of synch with the code, the code will always serve as the canonical representation of the design it embodies.

I believe such reasoning constitutes a scarecrow argument in that it presents an image of design documentation as necessarily so detailed and rigorous that it is fragile and brittle. Certainly it is possible to write design documentation in that manner, but it is also possible to make it quite robust by exercising some common sense regarding content and level of detail.

To the XPers who promote such fallacies, I would ask this:

“If you believe you can write code in such a way that the cost of change becomes negligible, why can’t you employ those same techniques to write design documentation with the same properties? A design document does not demand the same accuracy or contain the same complexity as source code; so why can’t you just refactor a design document with the same ease with which you refactor your code?”

This inconsistency points to “the code is the design” argument as a failed attempt to rationalize personal preference. Twiddling with the code is fun, twiddling with diagrams is not (apparently).

Conclusion

Explicit consideration of design as a precursor to implementation has numerous benefits, most of which have their origin in the limited abilities of the brain to cope with complexity. Embarrassingly, there are those in our occupation who would deny the applicability of the mechanisms commonly employed in other fields to cope with these limitations. Abstraction, planning and forethought are as useful to software engineers as civil engineers. Design recovery from complex artifacts is just as difficult for us as for those in other construction-based occupations.

To get value from design documentation:

Make it a part of your development cycle - don’t treat it as an optional afterthought. Document as part of the design of each subsystem (NB: design documentation does not imply BDUF).
Keep it as concise as possible, in the interests of maintainability.
Eschew CASE tools offering round trip engineering and use a simple drawing tool (personally, I like the UML stencils in Visio).
Concentrate on capturing dynamic behavior rather than static structure.

First published 10 Jun 2004 at http://www.hacknot.info/hacknot/action/showEntry?eid=57 ↩
http://www.agilemanifesto.org ↩
Extreme Programming / Agile Methods ↩
First published 27 Jan 2004 at http://www.hacknot.info/hacknot/action/showEntry?eid=46 ↩

Oral Documentation: Not Worth the Paper it’s Written On1

FUDD: Fear, Uncertainty, Doubt and Design Documentation4