How to write down/share unbiquitous language definitions in Domain Driven Design?

Question

Domain-Driven Design suggests to seperate applications into Bounded Contexts. Each context has its own set of specific, unambiguous words, which collectively make up the Ubiquitous Language.

In the process of finding the Contexts and the Language for a project, a team will probably generate several pictures of Contexts, and a list of terms of the Language.

How do you go about writing these down? Do you write on paper, or digitally? If digital, do you use text files, wikis, or as comments in code?

I see the following issues that may arise:

• How to bring new developers up to speed, when they join the team somewhen during the development process?
• How to keep documentation up-to-date during the dynamic nature of an agile development process?
• How do you make sure that the tooling does not get in the way of development, so that developers do not ditch "documentation" in order get to work?

Answer 1

The Ubiquitous Language is not so much a design artifact, like a class diagram, as it is a discovery by conversation — a process. If done right, the Ubiquitous Language is not a document. It is a consideration you take when naming something significant in the software system. It permeates all other documents by the names that things and processes are given. The software system itself becomes the documentation of the Ubiquitous Language, because classes, methods, variables, packages, diagrams and test cases all include this language.

This is where Behavior Driven Development pairs well with Domain Driven Design, because properly written behavior driven tests use the Ubiquitous Language. BDD tests should use the same terms and phrasing to describe the application behavior that is utilized by real end users to describe their business processes. So BDD tests written in Gherkin can be yet another reinforcement of the Ubiquitous Language.

Nearly every artifact of the software system, from the requirements, to use case diagrams, class diagrams, to code, should use the same Ubiquitous Language.

To be clear, a simple "ubiquitous language dictionary" is not enough. A dictionary of terms is good to have, but I can tell you from experience that people tend to forget where this dictionary is, and so it goes unused. You spend most of your time e-mailing teammates a link to this document.

There is no official "Ubiquitous Language Document". Remember the important part of Ubiquitous Language is the "ubiquitous" part:

Existing or being everywhere, especially at the same time; omnipresent: ubiquitous fog; ubiquitous little ants.

If you need a reference document of terms, create one. Keep it simple. Word document, wiki, doesn't matter. Point other people to it, and know that you will continually do so until the end of the project. The Ubiquitous Language should be everywhere to begin with from requirements to documentation to code. To understand even a single use case is to begin understanding the Ubiquitous Language.

Answer 2

The point of DDD is that terms are universal and commonly understood across the piece. Developers should speak the same language as the business they are supporting. If you find that this knowledge doesn't exist consistently across the piece, then that should immediately set alarm bells ringing. N.B. the knowledge may simply be in everyone's heads rather than written down formally in detail, but the point it, is should be somewhere.

With regards to your specific questions:

How to bring new developers up to speed, when they join the team somewhere during the development process?

This needn't be a lengthy tome you have to write and wade through each time. A sheet or two of bullet points should suffice - especially if the terms are commonly understood.

How to keep documentation up-to-date during the dynamic nature of an agile development process?

Keep these in a project management tool or via some other dynamic method e.g. a wiki. The point is it should be easily updatable. If it is on some protected storage, access limited or unduly moderated, expect it to go stale in fairly short it order. These should be shared documents although ideally, somebody should own them to make sure they don't go too off piste.

How do you make sure that the tooling does not get in the way of development, so that developers do not ditch "documentation" in order get to work?

As earlier described, your tooling should actually be helping you here so choice of tool is key. If you're having to go into half a dozen tools to work a story, then that isn't going to be a very productive process.