Modelling Guidelines

This page lists remarks on creating a software architecture and design document in general and it lists hints on getting along with the tool crystal_facet_uml. As all tools, this program has its strengths and weaknesses. This page helps in making use of the strenghts.

crystal_facet_uml Hints

Tree Structure

Diagrams are organized as a tree. Start the root of the tree explaining the document structure. At the second level of the tree, list the main areas to be shown, for example based on the arc42 template :

  • Introduction and Goals

  • Constraints

  • Context and Scope (show the system boundary, what is outside, what use-cases exist)

  • Solution Strategy

  • Building Block View,

  • Runtime View,

  • Deployment View,

  • Crosscutting Concepts,

  • Architectural Decisions (show alternatives, give a rationale),

  • Quality Requirements

  • Risks and Technical Debt

  • Glossary (table showing Context, Term and Description)


Put only few elements into each diagram. This increases understandability of the main purpuse of the diagram. Put further aspects of a topic into a separate diagram. Do not hesitate to copy an element from one diagram to the next. This is what crystal_facet_uml is good at: it keeps the model in sync.

General Hints on Architecture Documentation

Problem vs. Solution

Distinguish things that are

  • given constraints (problem space),

  • decisions, chosen and rejected alternatives and

  • the designed solution


Names of things are crucial: If the reader gets a wrong understanding by the name of an element, a hundred correct sentences of describing text cannot set this straight again.


Every design element needs a description, maybe a list of responsibilities: What shall this element do, what is it for? Names alone cannot explain a system part.

Precise sentences

Be precise: Write in active form, e.g. The persistence component shall store and retrieve binary data records indentified by string-based keys.

Distinguish similar things

Things that are similar but not the same shall be different entities when modelling. E.g. The process in which an example application runs may be different from the storage location and may be different from the software-component. These are three things: Example_App_Process (Type: Node), Example_App_ObjectFile (Type:Artifact) and Example_App_SWComponent (Type:Component).