Death by buzzwords

The design viewpoint expresses the logical components and their structural relationships. It also expresses their dynamics in terms of collaborations. The realization viewpoint expresses how the logical and process view elements are implemented in the system.

It's our responsibility to continually provide access to low-risk high-yield benefits and collaboratively administrate economically sound materials while promoting personal employee growth.

When a developer book starts talking like a guy from a marketing department, you know that something is not going as planned. But why these phrases are not comprehensible to the point that they make little sense out of a strong context, with an attached glossary? 

Well, one is a fictional quote from the Dilbert Mission Statement generator, so we can forgive that one. But the other is from an actual book. It's not easy to find out which is the real one, but if I tell you the book title (Building web applications with UML, by Jim Conallen) you can make a guess based on the topic.

I'm sure this is a great book for large companies, but it is really a torture to read for a developer which wants to learn how to design a web-based system, and not being submerged in mumbo-jumbo. Maybe because according to that process you have to update 5 diagrams before writing a single JSP, but the main problem of this book and of lots of technical writings is the jargon which they are written in: buzzwords.

Buzzwords

According to Wikipedia, a buzzword is

 a term of art or technical jargon that has begun to see use in the wider society outside of its originally narrow technical context by nonspecialists who use the term vaguely or imprecisely. Labelling a term a "buzzword" often pejoratively implies that it is now used pretentiously and inappropriately by individuals with little understanding of its actual meaning who are most interested in impressing others by making their discourse sound more esoteric, obscure, and technical than it otherwise would be.  Buzzwords differ from jargon in that jargon is esoteric but precisely defined terminology used for ease of communication between specialists.

and that is a great definition. When someone talks about a server with good reliability and availability, he's describing an actual mathematical function or he is generic? When there is a performance problem in infrastructure, where you should look? And if your site will produce great mashups, what the hell it will be doing?

As you can see from the definition and these brief examples, generic words and expressions are the death of communication, especially in a technical field which needs mathematical-like precision to work. You can't just use simple English words to describe technical concepts without the risk of being misinterpreted, or not understood at all.

Buzzwords like process and component are very overloaded, and have multiple meaning that we can never tie them to (by the way, overloading is the creation of methods with the same name but that differs in signature can be distinguished, for example by their parameters types; overloading itself is a precise term, but overloaded terms are very vague.)

Maybe we should establish a blacklist of words that cannot be used in technical writing: I propose component, business, process, and analysis for starters, and maybe also folksonomy and web 2.0.

Patterns

While Big Design Up Front methodologies are loaded with buzzwords, code-related entities and practices have usually precise and specific names which marketeers can't hijack. Continuous Integration is the practice of integrating changesets and execute quality control in real time; Test-Driven Development is the practice of writing tests before the code they exercise to use them as a design instrument. These terms have no meaning outside of their original definition.

This is somewhat similar to what we already do with patterns, which have very specific names to identify higher-level models than the class-interface-object-method defined in the code. Pattern names are also always passed to ucfirst(), since they are proper nouns. Whenever you write about an Adapter or Bridge, you should use the capitalization unless you are in a very technical context. In docblock comments, I always use capitalization anyway for patterns names as they really stand out.

The result of using proper nouns and a definition close to their code representation is that a pattern cannot be used as a buzzword, since it presents some roles the classes and methods must fulfill. Patterns always have some differences in their implementations, but this is their very nature. They are higher-level models, so they lack some refinement which depends on the particular use case; their usefulness resides in trasmitting distilled information about the classes structure or behavior.

If Building web applications with UML called phases Donatello, Leonardo, Michelangelo and Raphael, instead of Inception, Elaboration, Construction and Transition, I would have been happier even if these pattern-like names suck. First, the lack of actual meaning would be equivalent to the original names for the average developer. Second, I would remember all their names without straining my memory. Finally, I will also instantly know their order (alphabetic).

Conclusion

When I'll see a methodology book juggling around non code-related terms as invariable words (or pair of words), and assigning a precise definition to each, I'll read it cover to cover and keep it on my desk. Ideally, we should be able to build a wiki by giving to each term its own page, and make these concepts first-class citizens.

However, such a book already exists:

Does the practice of sitting together mean that multisite teams can't "do XP"? Chapter 21, "Purity," explores this question in more depth; but the simple answer is no, teams can be distributed and do XP. Practices are theories, predictions. "Sit Together" predicts that the more face time you have, the more humane and productive the project. If you have a multisite project and everything is going well, keep doing what you're doing. If you have problems, think about ways to sit together more, even if it means traveling. -- Kent Beck, Extreme Programming Explained