1. Ubiquitous Language
2. Modeling Out Loud
3. One Team, One Language
4. Documents and Diagrams
   1. Written Design Documents
   2. Executable Bedrock
5. Explanatory Models

Ubiquitous Language

• Developers and domain experts come to a project with their own jargon and ways of discussing issues.
• Without explicit intervention, language can become fractured, with different teams developing different dialects to talk about similar issues. This happens not just between developers and domain experts, but between developers and other developers as different teams work on their own parts of the problem.
• Language fracturing incurs notable overhead costs:
  • Information is no longer free-flowing. 'Bilingual' team members become bottlenecks that handle the translation of all information between dialects.
  • Translation takes time and effort, and so does clearing up mistranslations
  • Translation muddles model concepts, leading to destructive refactoring of code (ie. refactoring resulting in a loss of encapsulated intent and meaning)
  • Translation blunts communication and makes it hard to encapsulate the logic of a business process fully when knowledge crunching.
• No one dialect can be a common language because none will serve the needs of every team member.
• To avoid the aforementioned costs, a conscious effort must be made by the team to develop a common language that can be used ubiquitously across all work on the project.
• The vocabulary of the ubiquitous language should include:
  • The names of classes and prominent operations
  • Terms to discuss rules that have been made explicit in the model
  • Terms from high-level organizing principles imposed on the model (such as context maps and large-scale structures)
  • The names of patterns the team commonly applies to the domain model
• The meanings of words and phrases echo the semantics of the model.
• The language should be used:
  • By developers to describe not only system artifacts (eg. files), but tasks and functionality
  • By developers and domain experts to communicate with each other
  • By domain experts to communicate amongst themselves about requirements, development planning and features.
• The more pervasively the language is used, the more smoothly understanding will flow. Some principles to follow:

1. Use the model as the backbone of the language. Commit the team to using the language in all communication, including speech, writing, in diagrams and in code.
2. When you encounter difficulties with the language, experiment with alternative expressions which reflect alternative models. Then refactor the code to conform to the new model
3. Recognize that a change in the language is a change to the model
4. Domain experts should object to terms or structures that are awkward or inadequate to convey domain understanding, while developers should watch for ambiguity or inconsistency that will trip up design.

• With a ubiquitous language, the model becomes more than a design artifact, it becomes integral to everything developers and domain experts do together. It carries structural and semiotic information

Modeling Out Loud

• Deriving a useful model requires the use of multiple, complementary ways of thinking about a problem:
  • Visual/spatial reasoning through diagrams
  • Analytical reasoning with methodical analysis and design
  • The "feel" of the code (professional intuition?)
  • Linguistic reasoning
• To refine a model using your linguistic abilities, try describing various constructs from your model out loud and listen for rough edges (is it too vague? too verbose?)
• Humans have a natural ability to create and refine languages. Throughout history, when people without a common language come together for a common task (usually commerce) they will invent one, called a pidgin. Pidgins aren't comprehensive, so it's not possible to communicate anything you want through them, but are instead well-suited for effective communication when discussing the task at hand. When people talk, they naturally discover differences in interpretation and the meaning of words and naturally resolve those differences, smoothing out rough spots in language.
• Because of this ability, as we use the language in more discussions we become more fluent and teach each other its nuances, coming to a shared understanding of concepts in a way that never happens with diagrams and documents.

Takeaway: Play with the model as you talk about the system. Describe scenarios out loud using the elements and interactions of the model, combining concepts in ways allowed by the model. Find easier ways to say what you need to say, and then take those new ideas back down to the diagrams and code.

One Team, One Language

• There should be no need to "shield" business experts from the domain model. If sophisticated domain experts don't understand the model, there is something wrong with the model. If users find the model confusing, you should refine the model with them.
• Domain experts can use the language of the model in writing use cases or even acceptance tests.
• Multiplicity of language is expected and necessary. Developers have an extensive jargon they need to discuss the technical aspects of a system. Users will also have specialized jargon that extends beyond the scope of the application and the understanding of developers. These are extensions to the language.

Documents and Diagrams

• UML diagrams cannot convey two important aspects of a model:
  • The meaning of the concepts it represents
  • What the objects are meant to do
• The model is not the diagram.
• Diagrams (eg UML diagrams) are a means of communication and explanation, and can be used to anchor discussion and facilitate brainstorming.
  • Diagrams serve this purpose best when they are minimal, and don't overwhelm the reader with meaningless information
  • They should simplify, explain, and incorporate a bit of nonstandard notation when it clarifies their point.
  • They should show design constraints without being design specifications
  • They should represent the skeletons of ideas
• The vital detail about the design is captured in code. A well-written implementation should be transparent, revealing the model underlying it.
  • Supplemental diagrams and documents can guide people's attention to central points
  • Natural language discussion can fill in the nuances of meaning

Written Design Documents

• Spoken communication is critical to connecting everyone to the model, but groups of any size will also probably need the stability and share-ability of written documents, but creating good documents can be challenge

Two general guidelines for evaluating a document:

1. Documents should complement code and speech
   • A document shouldn't try to do what the code already does well, which is providing an exact specification of program behaviour
   • Documents should be used to illuminate meaning, give insight into large-scale structures,focus attention, clarify design intent when doing so through code alone is impossible
2. Documents should work for a living and stay current
   • Written documentation should take whatever form will communicate ideas with the team most effectively. If that happens to be Word documents, use those. If a set of casual sketches posted on the walls works better with your team's philosophy and communication style, you could do that instead.
   • To effectively communicate the state of the project, written documents should be living documents. If the information changes, the document needs to change. If the language changes, the document also needs to change.
   • Let the ubiquitous language and its evolution be your guide to choosing documents that live and get woven into the project's activity.

Executable Bedrock

• While code is 'closer to the ground' than other documents, it can still mislead and isn't guaranteed to be accurate.
• Code does accurately describe the behaviour of a program, but as names, comments and organization decisions become older as other changes are made, the code's ability to convey intention can drift
• It takes fastidiousness to write code that doesn't just do the right thing but also says the right thing (for more on this, see Clean Code)

Explanatory Models

• One model should underlie implementation, design and team communication. Having separate models for these poses a hazard
• Having different "views" of the model (explanatory models) can be valuable in some cases:
  • As an education aid, to teach about the domain
  • To have 'scoped' models that model a particular topic
• It's helpful to avoid UML in these models to avoid any false impression of correspondence with the software design
• To avoid confusion, everyone must be conscious of the distinction between a project's model and its explanatory models