As in any activity, fast, easy and clear communication is essential for a good performance.
In a software development project, both domain experts and developers have their own language, with its own jargon and specificities. Both team member types are usually unaware of the others language, so it must be created a common language that everyone can understand without any ambiguity.
In a project context, the domain model is the core tool common to both domain and implementation. So it is only natural to create that common language on top of the domain model. This common language is called Ubiquitous Language.
The Ubiquitous Language will include the terms used to discuss the model and the high level principles and patterns incorporated into the model. It must be used as much as possible, among developers, domain experts and between both of them.
This language should be used in all communication within the team, in the code, in diagrams, in project specifications and in requirements. It is core to the development process, to such an extent that a change in the Ubiquitous Language implies a change to the model and the re-factoring of the code itself so that classes, methods and variables naming comply with the language changes, as well as the re-factoring of any documentation and comments within the code.
Written design documents are important to formalise and stabilize knowledge and decisions made. Nevertheless they should not be seen as a core need, but instead as a complement to spoken word and, more importantly, to the code itself. Running code is not ambiguous, it does not fall out of sync and, if clean and transparent, it becomes the best design documentation.
Unfortunately, code as a design document has its limitations and, at some point, written documents become necessary. Nevertheless, a written document should only be used if:
- it doesn’t try to document what code is already documenting well
- it is useful, meaning that it is frequently used
- it stays current