The project may already have established a glossary – some business analysts start one up as part of their routine, which is great for ensuring clarification in the communication and documentation with regards to important terms, abbreviations and synonyms.
So why maintain a glossary in the solution architecture document? Well, first of all, it ensures that one gets established if no-one else does it. Secondly, I prefer to maintain a glossary that helps readers of my documentation understand key concepts. It often helps define elements in the information model presented in a later chapter.
The description should be an exact copy of the definition in the project’s glossary, if one exists. If the architectural glossary is the only one in the project, the architect must be relentless in achieving consensus on the descriptions across the project team and all its stakeholders. And, unfortunately, the architect is often also quite alone in sticking to the agreed terms and descriptions, but someone needs to do it to avoid misunderstandings or wasting time on repetitious explaining of previously defines terms.
In addition to describing each term, I also comment on its architectural consequences, which are often expressed in terms of necessary features and information entities.
I recommend that this chapter contains a table with the following columns:
|Simulation||A set of possible outcomes randomized within ranges assigned to the relevant factors.||The design builds on a fast math library to make the necessary calculations.|
|Factor||A variable or constant that has a bearing on the outcome of an investment.||The design builds on a rich user interface component library to achieve the necessary usability in inputting and editing factors.|
|Model||A container of factors and a simulation.||The model entity contains the defined factors and the most recently generated simulation.|