Modeling Guidelines

This section lists hints on efficiently using the tool crystal-facet-uml and provides some general remarks on creating a software architecture and design document.

crystal-facet-uml Hints

Modelling aspects that are special to the tool crystal-facet-uml are describes in this section.

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 :

In case you show several layers of abstraction, each building block may contain its sub-blocks, sub-blocks may again show sub-sub-blocks. In this case, structure the specification of the sub-blocks in the same way: apply the proposed folder structure recursively, omitting possibly empty or superfluous folders.


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.

When distributing different aspects to different diagrams, a remaining challenge may be that there is no filter on features and relationships. If e.g. two classes are connected via a generalization arrow and an aggregation arrow, each diagram will show both arrows even if only one is of interest for the shown aspect (except for interaction diagrams).

Solutions may be:

  • Define a port at a parent to bundle multiple communication paths of children

  • Separate abstract classes/components/blocks and their specializations


Put a prefix to all your elements denoting its namespace. You can then distinguish a GLOBAL_START_STATE from an AUDIO_START_STATE or global::start from audio::start.

To achieve a more compact layout of an element, one may insert space characters into names. (In case names get long, the space allows for a linebreak).

Attic/Storage room

If you are not sure if you really want to delete elements, 1) copy them to an attic-diagram and then 2) delete them from the original diagram.


To change the positions of classifiers anf features, drag these to other locations. Relationships can only be dragged in sequence and timing diagrams. Relationships in other diagrams are auto-layouted. crystal-facet-uml prevents to cross/overlay these two types of relationships: . If the layouting result is still inappropriate, move classifiers and features to other positions.

General Hints on Architecture Documentation

This section povides some general remarks on creating a software architecture and detailed design document.

Problem vs. Solution

Distinguish things that are

  • given constraints (problem space),

  • decisions, rejected alternatives and

  • the selected 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 identified 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).