Wednesday, March 15, 2006

Jargon Clash

(C) 2006 Thomas Jacob

The construction of a system is a progression from one stage of clarity to the next.

1. We start with hazy requirements - It's a three-line requirement doc!
2. We try to gather more details - Now, what could this be?
3. We feel we have achieved enough clarity - Oh, that's what he meant!
4. We start to implement the system. - What could go wrong? It's clear and easy.
5. ...and yet, in the final count, the system fails to match the user's expectations/requirements.

Often, the problem lies in the inaccurate representation of facts and requirements. In this article, we explore one of the causes for this.

The Quest For The Holy Grail
The importance of capturing the requirements correctly (as a "Requirement-Model") cannot be overemphasized. After all, the system is built to satisfy the requirements of the users. If we understand the requirements incorrectly, we have an inaccurate Requirement-Model, and the system (which is based on it) will not, cannot be successful.

A major obstacle in our quest for the perfect Requirement-Model is the lack of in-depth knowledge about the field in which the system will be used. This is unavoidable as one cannot be an expert in everything. And that's just as well because what's required of a maker of a paintbrush is that he should be able to make the paintbrush well, not that he should be able to paint well! There is no need for the designer of a CD-player to be a composer as well (though of course, it helps the cause if he "understands" music). It's horse for courses and that's why you have been chosen to develop the system and not the user.

Drinking From The Poisoned Cup!
We need to close the gap in our understanding of the requirements (The system needs to be built, right?) by asking the users for further details. The users might explain things in a seemingly familiar language, but the words could mean something entirely different than the meaning you got. Beware of Jargon-Clash! The user and you, both are experts, and experts, almost as if by definition, tend to use jargon. What you hear and get may not be what they mean!

A trivial, stupid(?) and impossible(?) example: You are implementing a distributed system for a retailing chain. The user says that the client needs to retain the bill. You could very well take thisthis down and, justifiably, note that the bill information needs to be stored at the client-side and go "Wow! Finally...I get to do distributed databases!". Probably all the user would have meant was the the customer (client for the user) needed to be given a printed bill!

Another, closer-to-reality example. The term "ATM" would mean "Automated Teller Machine" (the cash-dispensing type) to the "normal" user but to a networking professional, ATM would mean "Asynchronous Transfer Mode", a technology for networking. What then would an ATM network be? And couldn't there be ATM networks which use ATM technology for the network? Think about the very-many ambiguous conversations possible!

The Jargon-Clash isn't limited to the "unsavvy user, savvy developer" system-construction scenario either. In fact, the more similar the jargon of the user and the jargon of the developer, the higher the probability and impact of Jargon-Clash is. What's worse is that the Jargon-Clash will be less obvious. The effects may become evident only at an advanced stage of the project.
Example: Computer networking and telecom are closely related, especially in this age of Internet telephony. But the term TCP, for a network programmer, would refer to the TCP/IP communication protocol and to the telecom profession would mean a Trunk Control Program.

It also helps if the user too could be made aware of Jargon-Clash. Jargon-Clash could lead to destruction of mutual respect between the user and the developer. But surely, everybody knows what pinging is! How can he be so stupid? The situation now would be, as Strother Martin's character wryly observed in the film Cool Hand Luke, "What we've got here is failure to communicate." Every concern, every requirement is not conveyed and the accuracy of the Requirement-Model is affected.

For want of a nail, a kingdom can be lost and for lack of an accurate Requirement-Model, a system will be doomed to fail.

Poison Is The Cure
Pass everything the user says through the filter of Jargon-Clash awareness.

Try to agree upon a common vocabulary and clearly define each term of relevance. Make a glossary or a project-specific dictionary. It is very important to disambiguate, not only for the accurate elicitation of requirements from user, but also for the ease of implementation.

Construct new terms (a new jargon) if needed, if doing so would -
a) make things less ambiguous, and
b) improve the effectiveness of communication.
Alternate styles of capitalization or the merging of words would suffice in many cases to remind the reader/user that we are using the term in a special meaning.

It bugs readers no end to see repeating groups of words. Think "documentation of user-requirements" instead of Requirement-Model or "the problems caused by the common terms in the user's and developer's jargon" instead of Jargon-Clash. Abbreviate effectively, but do not make things too abstruse.

Validate your Requirement-Model with the user if possible, and then, using the mutually-agreed-upon non-ambiguous vocabulary. If properly validated, the Requirement-Model would simplify the onerous task of system-development considerably.

Ambiguous terms corrupt the Requirement-Model.
Equivocal Requirement Model = A Failed System.
The corruption propagates and gets magnified.
The developed system turns out to be different from what is required.
Users ditch the system. Wasted time, wasted effort.

Beware of Jargon-Clash.
Disambiguate, at any cost.
Even by inventing a new jargon!

- Thomas Jacob


Saturday, March 04, 2006

Advice for language designers

I strongly felt then, as I still do, that there is no one right way of writing every program, and a language designer has no business trying to force programmers to use a particular style. - Stroustrup

dynamic_cast prerequisite

A dynamic cast is performed run-time. A prerequisite for using the dynamic cast operator is the existence of at least one virtual member function in the base class.