Imagine I told you “Go do 5125558679”. I bet you’d be a bit perplexed. On the other hand, if I told you “Please call Tom at 512-555-8679 and give him an update on the project status,” you’d have a decent idea what to do. And, if I handed you a piece of paper with just 5125558679 written on it coupled with the verbal request, that would probably be sufficient to complete the task. Of course, if you needed Tom’s number in the future, you might have trouble finding it.
Unfortunately, a lot of SRSs I see look like “5125558679.” And, I’m afraid to admit, some of the SRSs I contribute to make a giant leap forward and looking like “512-555-8679.” They have the critical information people need right now. But, no real context. We’re all moving so fast, that we tend to only have time for the critical.
But, what is the cost of this? Those intimately involved with the project know what to do, but anyone coming in fresh is totally lost. Further, over time, even those intimately involved can forget the meaning. Documents in which a lot of effort was invested become at most marginally useful.
When writing documents, please remember your audience is typically not just the audience you know about now, but also unknown readers in the future. Give them a little context. In fact, I have some I’m working on right now that I realize could use a few sentences that would add a lot of context for that unknown reader…
