- Jack Be Nimble
- Wicked Problems and Gordian Knots
- Jack Be Quick
- Jack and Jacqueline Jump over the Candlestick
- Agile Business Analysis and Iterative Development Cycles
- And Jill Came Tumbling After
- Knowledge Artifacts
- Jack Sprat Could Eat No Fat
- Traditional Business Analysis
- The Requirements Document
- They Have Licked the Platter Clean
This chapter is from the book
This chapter is from the book
This chapter is from the book
And Jill Came Tumbling After
There is always someone coming after you; the product you build today could well last several decades. If you don’t believe that, ask your IT manager how old some of the company’s still-operating software is. Don’t be surprised if you find systems older than you. Change is happening constantly, which means we must constantly maintain our systems, sometimes for several decades, to keep them relevant.
Suppose for a moment that it is your job to modify a system that was built, say, 15 years ago.
It is the rationale for your decisions and the product’s functionality that you must leave behind for others.
What documentation would you find helpful? What the system does? Nope, you can get that from reading its code or observing its output. The thing you can’t get from the code or output is why it does it. And almost always, when you know why something is happening, it becomes much easier to know what you must do to change it.
It is the rationale for your decisions and the product’s functionality that you must leave behind for others. We suggest—very strongly—that your design decisions, your explanations as to why a process works the way it does, the reasons you give as to why particular data are kept should be recorded in some form and guarded.
You should also annotate any models you build with their rationale. Why is an activity part of the process when it doesn’t seem to make sense? Your added rationale tells future generations why. Why was one solution chosen ahead of others? Your rationale tells why.
The rationale is the minimum you leave behind for others. There is more, but not too much more.
Documentation
Documentation has become something of a dirty word. When the Agile Manifesto mentioned that working software was valued more than documentation, many overenthusiastic acolytes took this to mean that no documentation—absolutely none—would be even more valuable. Fortunately, wiser heads have prevailed, and we know that a limited amount of documentation is both necessary and desirable.
Whatever your attitude to documentation, it should be borne in mind that here we are talking about documentation that is produced as a natural by-product of the work; it is not something to be done afterward. And it is certainly not something that is destined to sit, unread and unloved, in filing cabinets or databases and never seen again.
The best documentation is produced as a natural by-product of doing work.
You need to leave something behind for others—the trail of breadcrumbs—(we’ll stop this nursery rhyme stuff soon) for the next person to follow in your footsteps, and hopefully Jill also leaves her own trail for others. Think of this as communication with your grandchildren. How much documentation do you need to leave behind for them?