13

Our company is in the process of converting a lot of manual business processes (and the associated institutional knowledge) into new enterprise software. The project is going really well, but as we proceed it is clear that there is a lot of confusion concerning terms and definitions on both the business and development sides.

I've been aware of Evan's arguments for forming a ubiquitous language for a while, but this is the first time I've needed to formally document them. As I look around and try to think about where/how to document our UL terms, I'm kind of lost.

How do other companies document ubiquitous language? Is this just a wiki-style dictionary? Is there some tool intended for this purpose?

  • 1
    This is a good start: thepaulrayner.com/blog/2013/05/07/…. I especially like this passage: "the important thing should be not that the domain is documented, it is that it is understood, and that this understanding is shared among everyone connected with developing the software." – Robert Harvey Dec 7 '15 at 16:16
  • Wow - what an awesome question. If I had this question, I'd look into EventStorming, and see if there's a sensible way to document the results of that process. – VoiceOfUnreason Dec 10 '15 at 20:23
4

You can treat "ubiquitious language documentation" as a software customization project: you need to take some software for documentation management and adapt it to your specific need. In software projects you normally start with gathering user needs, then you build information architecture and design solution and then you proceed to implementation. Below is the example of this process.

What are the user needs for it? In some organization people with different functions from different domains want to use common language dialect for describing their problems and solutions. This dialect will be defined solely by its vocabulary (words and figures of speech), since pronunciation is probably not important here and grammar will be based on literature form of the language. To document the dialect, you need to design a documentation structure that will be best suitable for managing a vocabulary (glossary of terms).

People may want to use this documentation for learning the meaning of the word or acronym, to find correct word by its synonym or definition or to learn all the words that compose the domain.

For these user needs, wiki is indeed a good choice. How does it fit? In good wiki system like Confluence or MediaWiki it is possible to:

  • Create an article for each term.
  • Define common structure of the articles in some template, so that they will contain some common sections, that can be used for aggregation.
  • Easily add links to term definitions in other wiki articles.
  • Build aggregate tables with term definitions and embed them in other documentation.

Currently I'm using Confluence for documenting information architecture and ubiquitous language definitions are part of it. Highest level of this documentation are domain articles. In every application there are multiple domains, e.g. security, payments etc. These domains are defined by a number of interactions of user with the system, which can be described via ubiquitous language, so I put definitions of these interactions in separate subpages, and definitions of terms introduced by these interactions in the subpages of interaction pages. I put aggregate tables on parent pages so it's possible to see, for example, of which scenarios consists the domain and which terms are defined in it.

When this documentation structure is done and I go to more detailed system specifications, I can simply refer to the IA and UL definitions of the scenarios e.g. "component A implements integration with system B to support interaction C (IA scenario link) by passing information about Z (UL link)".

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.