Documentation-Driven and Feedback-Driven Development
We would all like to be able to predict the future.
We would all like to be able to predict the future.
We are endowed with the ability to think rationally, which means our thoughts can be guided by logic. And logic is a great tool that could be used when we wish to predict the future. Logic is defined as the science of reasoning (similar to mathematics). Distinguishing correct reasoning from incorrect reasoning is the task of logic (also similar to mathematics).
Because reasoning is a mental activity based on performing inferences, we are tempted to use it to infer the connections between events (i.e., predict the future). One of the inferences, for example, could be: where there is smoke, there is fire. Someone reports that in some area they’ve noticed smoke, which gives us confidence to claim that the perceived smoke is caused by fire.
Based on these and similar examples, we may be tempted to infer future events based on the events that have already transpired (or are currently unrolling). Of course, some of those inferences/predictions will be less prone to end up being incorrect, while some other predictions may end up being way off mark. Our level of certainty varies depending on the nature of the events we are trying to predict.
Documenting the future and preparing for it
Once we arrive at the position where we are confident that our prediction of some significant future states or events is correct, we start working toward getting ready to respond to the predicted conditions. We make a plan.
Plans are quite useless if they are kept in someone’s head, so we would like to document them. When documenting our plans, we prefer to craft detailed documentation artifacts. Those documents, diagrams, spreadsheets, epics, user stories, tasks, cards, and tickets comprise our fully documented plan.
Now that we have agreed on what significant (to us) events and states the future brings, and we’ve also agreed on how we prefer to respond to what the future brings, we produce some kind of a blueprint. That blueprint is basically a collection of all the above artifacts (documents etc.), and is, according to everyone’s understanding, sufficient for us to start making the proposed changes happen.
In anticipation of the future state, we become eager to build a solution ahead of time. We embark upon building that solution by following the plan — by building according to our blueprint. We know what we want to build, now is just the question of how to go about building it.
What are our remaining challenges (now that we’re clear on what exactly are we to build)? Our challenges boil down to three things:
We may not have sufficient expertise required to build the desired solution
We may not have sufficient budget
We may not have enough time
We see that with documentation-driven development, we are constrained by the resources. We know what’s coming to us in the future, and now we’re scrambling to make sure we get ready for the upcoming changes.
What do we do when we can’t see the future?
Of course, seeing into the future is often a tricky proposition. The more complex our domain is, the less likely will we be able to predict with reasonable certainty what the future will bring.
Nevertheless, we cannot afford to just stop working in the cases when we don’t know what awaits us around the corner. So, what do we do then?
We can try to daydream and pretend that we know and fully understand our roadmap. However, such daydreaming and navel gazing is often proving to be fool’s gold. What’s causing that futile attitude? It’s mostly our fascination with the power of plans. Plans are seductive, and once we formulate a plan of action, it feels very natural to start working on the documentation. Once done, the documentation will serve as a blueprint, and we’ll then be ready to start building.
Only, we will be building castles in the sand. Such foolhardy approach often ends up being a colossal waste of time and money. Instead, it is more prudent to change our strategy. We need to abandon our attempts to produce copious documentation that we will use as a blueprint. A different approach is warranted. Before starting to document things, it is advisable to first gather some feedback.
Feedback-driven development
Unlike the situations where we know, with high degree of certainty, what is going to happen in the future and when it’s going to happen, we need feedback-driven development in the absence of that knowledge. This type of development is useful at times when the future is uncertain (which is quite often the case).
How do we obtain feedback? We do something, and then observe the consequences of our action. Yes, but what do we do? That’s the crucial question. Since we are not in the privileged position to know what exactly and when is something to happen, we must lower our expectations. Instead of crafting the plan and projecting the work that is going to get us in a proper shape to address the change that we anticipate is going to happen, we have no recourse but to hypothesize.
When hypothesizing, it is best to adopt the scientific approach. I have already elaborated on this approach in another article (Hypothesis-Driven Development). It may be helpful if the readers would familiarize themselves with that approach; I would not want to abuse readers’ attention here by repeating what’s already been described in that article.
In a nutshell, a hypothesis is based on a hunch, or a vague belief. To avoid wasting time and resources, those hunches or beliefs that are considered to be formulated as a hypothesis must be very small. The smaller the hypothesis is, the easier and quicker will it be to put it to test. After we put our hypothesis to the test, we obtain the much needed feedback. From that feedback we get enough valuable information that will help us decide what our next step will be.
Because of this orientation, I am now prone to call that process feedback-driven development. And because the only reasonable approach to that type of development is to take very small hunches and turn them into a tiny hypothesis, it is clear that feedback-driven development is gradual. One step at a time (and make sure each step is a tiny step).
How is feedback-driven development different from documentation-driven development?
The first thing that jumps at us when we’re comparing, side-by-side, two types of developments, is the scope. While documentation-driven development begins from a very clearly defined scope (“this much must be accomplished by such-and-such a date”), feedback-driven development does not have a concept we call scope. Neither does it have a concept called deadline.
So, without a scope and with no defined deadline, how is the feedback-driven development useful? Well, in the absence of a crystal ball that will tell us what the future holds in store for us, we can only continue working by relying on our wits. Each day brings new information to light, and because we don’t have a preconceived, predefined blueprint, we are free to adjust our sights based on the most recent information.
In contrast, once the work commences in the documentation-driven development arrangement, any new information that may subsequently come to life tends to be ignored. Or, at best, not ignored but earmarked to be addressed later.
Why is documentation-driven development apathetic toward new information?
Documentation-driven development is based on the conviction that all pertinent information that is needed for the successful delivery of the solution is known upfront. As such, we are not anticipating any new information that may later come to light and that may force to change our course. To stop the proceedings and to address the newly arrived information would therefore be delinquent.
Also, new information may disrupt the already arranged budget and schedule. It is for the sake of the success of the project that we must protect the teams from experiencing such disruptions.
Why is feedback-driven development apathetic toward scope?
As already mentioned, there is no scope nor deadlines in the feedback-driven development. Why is that? Isn’t it more prudent to invest some time into defining the effort that will be needed to deliver successful solution?
The only way we could size and formulate the effort needed to deliver the solution is if we could see into the future. But because for us the future looks uncertain while our current situation is volatile, we refuse to engage in daydreaming and any associated guesswork that would provide some sort of a scope and a schedule.
What do we do instead? We work on seeking feedback. But we cannot know ahead of time what the feedback will be (otherwise we wouldn’t have the need to seek feedback at all). It is impossible to think about the scope if we’re waiting on feedback.
What are some problems associated with feedback-driven development?
Given that feedback-driven development can only happen piecemeal, the biggest problem is the inability to present how much time/effort/money will be needed to deliver successful solution. Since feedback-driven development fully relies on the pursuit of feedback, it is impossible to know ahead of time what the feedback will be. Which means we can theorize that the successful solution may happen in a few days, or in a few weeks, or in a few months. That’s not a very comfortable position for the business owner who is negotiating the cost of doing business.
Another big problem is unfamiliarity with the scientific model. Most software developers and software teams have been trained to comprehend software products the same way we comprehend physical objects: if we ask the team to build us a table with a set of chairs, and then give the team precise blueprints, they will be able to give us fairly precise estimates. “This is how much it will cost to build according to this blueprint, and this is by when are we expecting to deliver those objects.”
Software doesn’t work like that. Software is never done (unless it gets decommissioned). While it is being built, and then even while in use, software is subjected to constant changes. Because of that, we cannot know the scope of effort ahead of time.
What are some problems associated with documentation-driven development?
As already mentioned, software is not finite product that, once built and delivered, stays put and doesn’t have to be worked on anymore. Documentation-driven development willfully ignores that aspect of software.
Furthermore, documentation-driven development leads to situations where teams end up scrambling. That scramble is due to the three documentation-driven development challenges already mentioned above:
We may not have sufficient expertise required to build the desired solution
We may not have sufficient budget
We may not have enough time
Given the clear-cut scope and the firm deadline typical for documentation-driven development initiatives, the moment the blueprint (i.e., the documentation) gets produced, the clock is on! There now begins the rush toward the finish line. And in the attempt to meet the deadline, teams often sacrifice some of the quality of the delivered product.
Conclusion
Whether we decide to go with documentation-driven development or with feedback-driven development would largely depend on the nature of the problem we are trying to address. If the problem is well defined with clear expectations and a known expected delivery date, documentation-driven development oftentimes seems like a more suitable approach. On the other hand, if the expectations are not crisp and clearly defined, feedback-driven development seems like a better option.