Sometime ago, my manager asked me to put together a plan to validate a very complex system of software, so I requested a specification from the development team. After all, what was I supposed to test unless there was some document of what the system was required to do? But none existed. The entire project started as a small group of people with requirements discussed orally and even though it had transitioned into hundreds of engineers that method of planning persisted. Each working around the idea of what they thought it was supposed to do. Besides leading to inevitable disconnects, their request to test this system was like someone handing you a random object you’ve never seen and ask you to make sure it works.
Since this was the first version, I drove the group to write a list of requirements for the system so we could figure out what to test. Since we were near the end of the development phase, some derided this effort as playing Jeopardy – here’s the answer, what was the question. I sent out a template for everyone to fill in with the various pieces they “knew” about and then took each person’s suggestions and put them into the same place. Sure enough, I got contradictory requirements leading to several shocked parties as they expressed: “Wait, if we have to do that, then I need to ….”. We sometimes find that we are under the delusion that we’ve communicated only to realize that we haven’t communicated at all. The written word provides a grounding for everyone to literally be on the same page.
Writing doesn’t just help in our communication with others, it also helps us. When my wife and I took a trip to Ecuador and Columbia 8 years ago, I carried a small book that I used to capture various ideas running through my brain: mostly random observations about the world. Originally, I planned to just write about these ideas and share with others on this blog, but what I discovered was that forcing myself to dwell on a topic for more than a passing observation allowed me to make more connections with other various ideas as well as clarify ideas in my head. Sometimes it’s easier for us to deal with abstractions without thinking about what lies underneath them and writing things down helped me penetrate that veil. Ultimately, having thought through how to express an idea improves our ability to clearly think about the idea ourselves. Writing let’s us practice that.
One common objection to writing requirement specifications is that no one will read them, but there is one person that most definitely will read them: the author. We often think of writing as being only for others but forget how much it can help ourselves too.
Photo Credit: FootMassagez cc
Leave a Reply