Writing For The Purpose of Reading

The reason we write is so that someone can read it in the future. Duh. When we’re writing requirements documents, or documenting processes, how often do we stop and think about who will be reading our documents? We need to make sure our writing will be easy to read for our audience.

Writing As Marketing

Sam Decker makes a great point about how marketing should use the language of the customer in his recent article. This is actually the 11th in a great series on marketing, if you aren’t reading Sam’s stuff, you should be.

Hit the bulls eye by writing in the language of the customer. To use the same terms, phrases, and straight-forward speak that a customer might use when asking someone else about your solution (and of course, they probably didn’t use the word ‘solution’)!

Sam Decker

Applied To Requirements

Product Managers and others in the “requirements space” all create requirements documents. We create different documents to achieve different goals. It isn’t enough to target our communication content for our audience – we also have to think about the vocabulary we choose to use.

As requirements people, we tend to be precise in our use of language – avoiding ambiguity at all costs. When offshoring, or dealing with multi-cultural teams in general, we also have to understand when terms have different meanings for different people. We also have to watch out for terms that have symbolic meaning, that suffer from varying interpretations.

This precision can come at a cost if we don’t take into account the domains of expertise of our readers, and the terms that they know. As Sam points out, we want to use the language of our audience when describing something.

This can be challenging for pedants like us – when there is a perfectly good, albiet obscure term, why replace it with a sequence of more common words? It goes against our nature. We want concise documents. But clarity (for the reader!) should not be sacrificed for brevity.

Applied To Process Documentation

In addition to documenting requirements, when we are working as business analysts, we also usually have to document existing processes. This is really only true for migration projects, but those represent almost all single-customer projects.

We should make sure that our documents use our customer’s terms when documenting these processes – not our own terms. The responsibility is ours to translate from the single-customer language to the multi-customer concepts.

Process documents are reviewed initially by business owners, and are eventually consumed by systems analysts or implementers. Maybe a glossary of terms is required to help a multi-customer implementation team deploy enterprise software for a client. The documents developed for, and validated by the customer should use the language of the customer.

Applied To Communication In General

When we’re in meetings, having conversations, writing emails, or in any other way communicating with our clients, we need to use their language. Product managers should come equipped with a universal translating device. While an initial conversation may start with industry-standardized terms, as client-specific equivalents are identified, the product manager or analyst should immediately create a substitution and use it in all future communication.

We also have to think about the backgrounds of our audiences. Here are a couple stupid things I’ve said in recent meetings with business owners (who have backgrounds in finance and the insurance industry):

• “From the flow, you can see that the process recurs, and will do what we need.” Translation: The process repeatedly calls itself until it reaches a decision point that forces it to stop. At least I didn’t specify that the process was tail-recursive.
• “The decomposition of the work is straightforward, we just establish the proper quanta for breaking down the work in each area”. Translation: Break down the work into reasonably sized chunks. What the hell was I thinking?

Pretty much everyone groans when a smug consultant mentions a priori conclusions about prioritization, or an “obvious” algorithm. I’m sure there were a couple groans when I talked about quanta. The use of recursion is even worse – to a programmer, it has a precise meaning. To a non-programmer, it simply means repitition. The dictionary example uses “The cancer recurred” – and I’m sure it doesn’t mean that the cancer cells were attacked by cancer. I actually introduced ambiguity by using a term that some people would find to be more precise (the process was walking down a hierarchical business-data-structure, processing elements along the way).

Conclusion

Thanks Sam for pointing out that we need to speak in the language of our customers. We can extend this idea to make sure we use words within the vocabulary of our audience as well.