Anecdote: Programmers Are Weird!
Symptoms: Customers who get frustrated talking to developers who are working as analysts. The jargon and abstraction overwhelms them.
Context: Projects where programmers act as analysts (i.e., programmer-analysts) yet lack training or experience in customer communications. Usually not projects where the customers are also technical personnel.
Motivations:
- Programmers like technology, like to talk about it, and spend much of their time immersed in it. It forms a comfortable language for them, including standards and conventions that simplify and clarify communication.
Programmers further develop writing habits (i.e., coding standards) that help produce more readable and maintainable code. They internalize these habits and tend to use them across the span of development activities. Yet despite programmers’ “comfort level” with these habits, the habits can be completely confusing to regular people.
Programmers develop writing habits that help produce more readable and maintainable code, but can be completely confusing to regular people.
- Programmers also like to work in the realm of abstractions: ideal cases and especially common cases that allow programmers to create a solution once and then apply it (with necessary modifications) across a wide range of cases.
Customers and end users tend to work in the world of the concrete: real, distinctive jobs to be done for real, distinctive clients – and with real, distinctive problems and complications and consequences that popup. While they may think about abstract general principles when they need to, their work biases them toward the concrete. Most end users don’t deal with abstractions to the degree that programmers do.
While customers may think about abstract general principles when they need to, their work biases them toward the concrete.
- For various reasons – cost, trying to facilitate communication, and simply not knowing any better being chief among them – many development organizations have programmers serving as programmer-analysts, but without training as suggested under the Trained Analysts pattern.
Problem: The problem, I hope, is obvious: programmer jargon can confuse customers and end users. That’s not news to anyone, and it’s a major consideration in many of the patterns in this book. But I want to draw particular attention to two common but confusing programmer habits: coding standards and abstractions.
Programming standards lead programmers to write (and sometimes talk) in odd-but-precise ways that have specific meanings to computers. And beyond that, we (I can be as guilty as anyone) like to show how clever we are by using these odd formulations in non-technical settings. It becomes a form of in-joke: “Let me just access the ICashMachine interface over here so I can instantiate some cash objects.” Our fellow programmers get the joke, laugh, and probably then try to top us. And if regular people took at us funny, shake their heads, and mutter “Geeks,” we take it as a badge of honor. They don’t get the joke, but we do.
And those odd formations really do serve a useful purpose in code; but boy, do they look odd! We stick an “I” in front of anything we “talk” to: IAccount, IBankSystem , ILeasingCompany. And as the examples above show, we like to jam together longStringsOfWordsThatNameSomething, and to use funny capitalization when we do so. And we like to use odd punctuation combinations, such as “==”. “::”, “->”, and “///”.
| And believe it or not, every one of those odd usages has a specific and useful meaning. I could teach it to you, even if you’re not a programmer. As a customer, you could learn how to understand it. But why should you have to? Those odd usages are designed to help us to talk to computers, not to people. Just because we geeks can understand them doesn’t mean those habits belong in a requirements discussion. And yet they often end up there. Even when they’re being serious, programmer-analysts who write documents and especially programmer-analysts who create models tend to sprinkle them liberally with coding standards, with their vision of how the code might look. That makes it harder for customers and end users to understand those documents. Since the audience for those documents is people, not computers, that’s just not a smart idea, no matter how compelling it seems to the programmers. |
|
Abstraction is a more insidious problem, because it has some real benefits during analysis as well as some real drawbacks. It’s important for analysts (including programmer-analysts) to identify general principles, commonalities, and other abstractions that can aid their understanding of the problem domain. But it’s also important to realize that customers and end users may not think in those abstractions; and trying to force them to do so may actually hinder communication. It’s all right to introduce an abstraction into the conversation and see if it helps; but you have to be ready to fall back on the concrete if the abstract doesn’t work.
There’s another potential problem with abstractions during analysis: they’re often a sign that you’re designing, not analyzing. When programmer-analysts start seeing possible solution abstractions, they may introduce those into the requirements documents. Not only can this confuse customers and end users, but it can also lead stakeholders to assume that these design concepts are actually requirements (as discussed under the That’s Design, Not Analysis antipattern).
Solution Name: Speak English!
| Solution: Fortunately, this is usually a self-correcting problem. Just remind programmer-analysts to rewrite their text or models and to revise their remarks to aim for a general audience. That should be enough to get them to correct themselves. |
|
In particular, ask programmer-analysts to strip out coding standards wherever they appear, unless the requirement they’re documenting is actually a coding requirement (such as a required interface or protocol or algorithm). And if they’re using abstractions that seem too far from your problem domain for you to understand, ask them to go back to specifics first. From there, ask them to talk you through to explain the benefits and purpose of the abstraction, including how they expect the abstraction will apply across a wide range of cases. And if they can’t do that, then explain to them that the abstraction may be useful as a design concept – and should be documented in their design notes – but is complicating matters when it comes to requirements.
Resulting Context: With a few reminders from customers and end users (and a few jokes at their expense, as needed), programmer-analysts should learn to communicate with a general audience.
Discussion: This antipattern can be a special case of another antipattern: The Department of Obfuscatory Verbiage. And the solution relies heavily on The Echo Effect: stakeholders have to let programmer-analysts know when they have failed to communicate. And the ultimate solution, of course, is Trained Analysts, whether they’re programmers by title or not.




-small.gif)






