1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
|
<!DOCTYPE section>
<section>
<title>Modeling Guidelines</title>
<para>
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.
</para>
<section>
<title>crystal-facet-uml Hints</title>
<para>
Modelling aspects that are special to the tool crystal-facet-uml
are describes in this section.
</para>
<section>
<title>Tree Structure</title>
<para>
Diagrams are organized as a tree.
The root diagram is the title page.
This can be used to state the project goal or
to explain the document structure.
At the second level of the tree, list the main areas to be shown,
for example based on the arc42 template <ulink url="https://arc42.org/overview/"/> :
<mediaobject>
<imageobject><imagedata fileref="5_modeling_hint_on_structure.png"/></imageobject>
</mediaobject>
</para>
</section>
<section>
<title>Focus</title>
<para>
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.
</para>
</section>
<section id="decoupling_mechanisms">
<title>Use Abstractions and Hierarchies</title>
<para>
When distributing different aspects to different diagrams,
a remaining challenge may be that there is no filter on features and relationships.
If for example 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).
</para>
<para>
Solutions may be:
<itemizedlist>
<listitem>
<para>
Add an hierarchy level, show only the outer elements in one diagram,
show only the contained elements in another diagram.
<mediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0005_add_hierarchy_level.svg" width="8cm"/></imageobject>
</mediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0011_higher_hierarchy_level.svg" width="8cm"/></imageobject>
</inlinemediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0012_detailed_level.svg" width="8cm"/></imageobject>
</inlinemediaobject>
</para>
</listitem>
<listitem>
<para>
Define a port at a parent
to bundle multiple communication paths of children.
<mediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0003_add_parent_ports.svg" width="8cm"/></imageobject>
</mediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0008_parents.svg" width="8cm"/></imageobject>
</inlinemediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0009_children.svg" width="8cm"/></imageobject>
</inlinemediaobject>
</para>
</listitem>
<listitem>
<para>
Separate abstract classes/components/blocks and their specializations
to hide details when showing the abstract concepts and vice versa.
<mediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0002_add_abstraction_level.svg" width="8cm"/></imageobject>
</mediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0006_abstract_components.svg" width="8cm"/></imageobject>
</inlinemediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0007_concrete_components.svg" width="8cm"/></imageobject>
</inlinemediaobject>
</para>
</listitem>
<listitem>
<para>
Extract methods to an interface to hide details when using the class.
<mediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0004_extract_interface.svg" width="8cm"/></imageobject>
</mediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0013_separate_interface.svg" width="8cm"/></imageobject>
</inlinemediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0010_interface_hidden.svg" width="8cm"/></imageobject>
</inlinemediaobject>
</para>
</listitem>
<listitem>
<para>
Add a topic-specific mediator class (e.g. a risk) that is only shown in selected diagrams.
<mediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0014_add_mediator_class.svg" width="8cm"/></imageobject>
</mediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0015_technical_solution.svg" width="8cm"/></imageobject>
</inlinemediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_modeling_hints_export/D0016_risk.svg" width="8cm"/></imageobject>
</inlinemediaobject>
</para>
</listitem>
<listitem>
<para>
If applicable, use an interaction diagram: Interaction-Overview, Communication, Sequence or Timing.
These hide features and relationships except the ones defined at the local diagram.
</para>
</listitem>
</itemizedlist>
</para>
</section>
<section>
<title>Namespaces</title>
<para>
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.
</para>
</section>
<section>
<title>Attic/Storage room</title>
<para>
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.
Note that copy, in contrast to a cut, keeps all relationships.
</para>
</section>
<section>
<title>Layout of Classifiers and Features</title>
<para>
To change the positions of classifiers and features, drag these to the target location.
Note that the relative position of classifiers towards each other affects
the layout of other diagrams also.
</para>
</section>
<section>
<title>Layout of Relationships</title>
<para>
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:
<inlinemediaobject>
<imageobject><imagedata fileref="5_rel_L7.svg" width="0.4cm"/></imageobject>
</inlinemediaobject>
<inlinemediaobject>
<imageobject><imagedata fileref="5_rel_JF.svg" width="0.4cm"/></imageobject>
</inlinemediaobject>
.
If the layouting result is still inappropriate, move classifiers and features to other positions.
</para>
</section>
</section>
<section>
<title>General Hints on Architecture Documentation</title>
<para>
This section povides some general remarks on creating a software architecture and detailed design document.
</para>
<section>
<title>Problem vs. Solution</title>
<para>
Distinguish things that are
<itemizedlist>
<listitem><para>given constraints (problem space),</para></listitem>
<listitem><para>decisions, rejected alternatives and</para></listitem>
<listitem><para>the selected solution</para></listitem>
</itemizedlist>
</para>
</section>
<section>
<title>Names</title>
<para>
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.
</para>
</section>
<section>
<title>Description</title>
<para>
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.
</para>
</section>
<section>
<title>Precise sentences</title>
<para>
Be precise: Write in active form, e.g. The persistence component shall store and retrieve
binary data records identified by string-based keys.
</para>
</section>
<section>
<title>Distinguish similar things</title>
<para>
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).
</para>
</section>
</section>
</section>
|
