The Cost of Poor Planning
In the video for this chapter, you learned about the historic planning blunder that was the U.S. government’s Bradley Fighting Vehicle (BFV). While it was eventually built as required and has served the U.S. military very well, it’s development was a classic case of severe bureaucratic mismanagement, taking the military 17 years to complete and costing the American taxpayer 15 billion dollars. This extraordinary planning blunder was the result of poorly documented and defined requirements, as well as a lack of understanding regarding the high cost of fixing errors late in project development, exemplified by the military’s “we’ll fix that in production” response when concerns were brought up.
Documentation errors not caught and addressed in the early planning stages will surface during development and cost more to correct.
This cost is proportional to when it is found: the later the discovery, the greater the cost.
The amount depends on the project development model.
The above figure shows the cost of making changes during project development across three different proposed project management models: waterfall, agile, and idealized agile.
Waterfall models, such as Six Sigma and the software development life cycle (SDLC), are the cheapest and easiest models for early changes such as the requirements and design phases of the project. However, the cost of making changes can get out of control once coding begins. By the time you get to production, changes can cost as much as 1000 times more than if you made them before coding. A later change requires all previous phases to be completely redone, which is not only expensive but frustrating for both project managers and developers.
Idealized agile is a hypothetical model in which Extreme Programming (XP), a type of agile development, is used in conjunction with a test-driven design (TDD) approach. In theory, this method reduces the feedback loop to minutes instead of the days, weeks, or months, usually seen in waterfall processes. Consequently, the cost of the change would likely never get out of control.
However, since an idealized agile model is simply that, idealized, we can assume that it won't likely be realized in practice. In reality, there are too many uncontrolled additional variables that will affect the cost of the change curve. The light blue line in the figure represents a far more appropriate curve typically seen in agile development projects. Rather than flatten out, it rises gently over time and throughout the project life cycle. The fact that it rises is not surprising or alarming. It shows the result of the development progression of a project. For example:
The codebase for a project grows over time, increasing the likelihood that a change will affect other areas in the code, which raises the cost following the growth.
In addition to the codebase increasing over time, so will the number of non-code artifacts. These include documentation, models, diagrams, etc. As the number of these non-code artifacts grows, so does the cost of a change. An agile approach reduces the cost of such changes but can never fully eliminate it.
Another common factor is that your process may not be perfectly agile. Agile development teams often find themselves attempting to work within very non-agile environments. Non-agile management may impose costly policies and procedures, such as lengthy documentation rules and coding standards to which your work must conform, or repeated technical reviews, all of which increase costs.
As an Agilist, your goal is to create high-value documentation. This means you produce less volume, but more direct and useful documentation than a traditional model. Agilists also don’t tolerate unnecessary bureaucracy. By removing unnecessary procedures from project plans, you can act on changes faster simply because you have less work to do.
Properly planning and modeling your project is essential to flatten your cost of the change curve. You can’t completely flatten it, but the earlier in the process you validate your development artifacts, the lower your cost of change curve will be.
Why Do you Document?
Documentation is a critical part of any system, and yet project managers and developers dread it. Documentation isn't just reference guides or instruction manuals; it's important pieces of information communicated clearly to a specific audience.
Why do you document? To communicate.
All right, maybe that’s too simple of a response. So let’s consider a few possibilities within that need for communication:
Your stakeholders requested the documentation. Creating it is a business decision: you are investing the resources of your project stakeholders in developing documentation; therefore, they should have the final say on whether their money is to be spent that way.
To define the interaction between multiple systems (typically called a contract model). Contract models are often required when an external group controls information that your system requires, such as a database. This should still be approved by your project stakeholders, as you’re spending their money.
To facilitate communication between remote teams. Many projects today are built by multiple teams in different locations. A team in India could be working on the same project with a team from France and the United States. Shared documentation expedites communication.
To support agile development which requires you to enable the next effort (or sprint) while producing your project deliverable for each sprint. It's important to develop the documentation needed to use, support, and maintain that deliverable while developing software.
To prepare for audits. Some systems are audited for security or government/corporate compliance standards. Such cases typically have certain requirements and need documentation showing how the process was followed.
I often document for my own benefit, like when I brainstorm or think through a complex problem. Documenting my processes helps keep my thoughts organized and lets me change direction or alter my course. Writing down ideas helps resolve any issues and can validate your decision.
There are many reasons why you could be asked to create a piece of documentation. The biggest is that an idea needs to be communicated.
Facilitate Communication Through Documentation
In the last section, we established that the purpose of writing documentation is to communicate information in the clearest manner possible to a specific audience. Now let's see how to write that documentation.
If you search for “principles of effective written communication” online, you’ll get quite a wide variety of hits, such as:
3 Key Principles of Effective Communication.
5 Principles of Effective Business Writing.
7 C’s of Effective Communication.
8 Top Tips for Effective Business Writing.
10 Principles of Effective Writing.
12 Principles of Effective Communication.
Shall I go on? How many principles of effective communication or effective writing are there? Three, seven, twelve, twenty? There is no set of concrete principles or rules, but rather general guidelines. However, when you get specific about them, everyone has an opinion.
You may already be familiar with a lot of these guidelines. So rather than make this a community college technical writing class, let me refer you to the following handout:
This is an excellent summary of the principles of effective writing described in the eBook Effective Written Communication by Vlad Krotov, PhD (2017). Not everything the author discusses will be relevant to writing client briefs, but it is a helpful resource if you need to refresh your basic writing skills.
For me, there are just a few things I like to keep in mind when I’m writing.
First, write with a clear purpose. You don't want to waste your time on unnecessary documentation, so be sure you understand the purpose before you begin.
Write with clarity. I love the linguistic playground that exists in the writings of William Shakespeare, but technical documentation is simply not a great place to explore such things. If you’re writing for a specific purpose, then use words and phrases that move the reader without wasting valuable time.
Be aware of your audience. I once walked into a graduate class on complex algorithms and data structures and was baffled when the professor’s teaching assistant began to introduce the basic components of a PC. The professor had mixed up his assistants’ assignments and sent them to the wrong classrooms. If you don’t understand your audience, your writing will not be effective. Know what your reader needs from your document so you can focus your writing. Beware of cultural phrases or expressions. Many years ago, I had a supervisor who, on a business trip to another country, ate more than she intended during a lunch meeting. When she couldn’t eat another bite, she leaned back in her chair, patted her stomach, and announced, “I am just stuffed!” Several people in the restaurant, including her lunch companions, turned and stared at her, many of them snickering. She had just told them all that she had become pregnant out of wedlock.
Use humor cautiously. I like using humor in my writing. If I’m entertained while I’m writing, then chances are the reader may be entertained as well, and an entertained reader pays attention. Be careful. Know your audience and only use humor if and when it is appropriate and within the context of the document.
Documentation such as a client brief is, in many ways, much simpler and less demanding than many other kinds of writing. There’s no pressure to be too creative, original, or find ways to keep your audience entertained. Flowery language is a taboo, so you don’t need a thesaurus at your fingertips. Your goal is to write as clearly and directly as possible. But that doesn’t mean it’s easy. Writing such documents well takes practice and ingenuity, and maybe a course like this one.
Let’s Recap!
Proper planning is vital to a project’s success.
Agile methodologies can flatten the cost-of-change curve.
The primary objective of all documentation is communication.
You can find tips for effective writing everywhere, and taking the time to review them and putting them into practice is worth the effort.
In the next chapter, we will discuss agile methodologies in greater detail, how to use them to document your projects, and how to make your documentation more effective by following a few rules for technical writers.
