There is a general problem in software, more pronounced in minimalist Agile efforts, of documents that look good at the time of writing, but do a poor job of transferring information. I call these “stump” documents because readers are stumped when they try to learn from them.

The main difference between stump and transferable documents is that transferable documents include all of the information they need to be stand-alone – fully understandable without help from the writer – while stump documents require some prior knowledge. Stump documents, by this definition, are not useful for transferring information to any reader who doesn’t match the document’s level of assumed knowledge.

A simple way to demonstrate the difference between stump and transferable documents is to look at two variations on a small note: “Liam, Tue. 1200” and “Meet Liam the designer at his office (on 2nd and 14th) at 1200 on Tuesday”. The first note is a stump: it works well enough for you because you know who Liam is and where you’re meeting. The second note is transferable: you could send it to a third-party in the same city and the note will make perfect sense and include all required information. If you were to send it to someone in a different city, you might need to expend the address.

All writers can write stump documents, but I see them more often in Agile environments. I think the reason Agile often falls into the stump trap is that documents are written as a response to something that the writers are looking at, not an abstract idea, and so they don’t feel the need to write down the context and all of the details. After all, it’s right there for all to see. But there are two pitfalls here. One is that some of what the writers are “seeing” is not really visible – they just remember details they’ve heard in meetings and don’t notice that they’re actually very obscure. The second is that what they’re looking at now might not be there in six months’ time. The result is a document that is unintelligible to new readers.

Most stump documents eventually become dead documents; because people forget things over time, even the writers will probably not understand the document a few months after writing it. This means stump documents are poor even at preserving information, not just at transferring it. In short, they’re of very little long-term utility.

Obviously, some documents are fine as stumps: they may be intended to live a very short time, and never be used to impart information to new employees, users and so on. But if you do need something long-term, something that can be used to impart information to new people – you’ll have to work to avoid writing stumps.