131 |
they don't give the documentation any structure. |
they don't give the documentation any structure. |
132 |
|
|
133 |
In the following sections, we first discuss the role of documentation |
In the following sections, we first discuss the role of documentation |
134 |
in software engineering in general, then bring the problem of the distinct |
in software engineering in general, then bring the problem of the separate |
135 |
documentation bodies into focus and present our solution and |
documentation bodies into focus and present our solution to linking and |
136 |
its implementation. Finally, we discuss our practical use of the tool |
its implementation. Finally, we discuss our experience from using the tool |
137 |
and conclude. |
and conclude. |
138 |
|
|
139 |
Background |
Background |
162 |
ideal software design process, and that there are several different |
ideal software design process, and that there are several different |
163 |
types of documentation at different levels of abstraction. |
types of documentation at different levels of abstraction. |
164 |
The steps listed above should produce |
The steps listed above should produce |
165 |
documentation which records requirements or design decisions and |
documentation which records requirements and design decisions, and |
166 |
could be referenced throughout the building of the |
could be referenced throughout the building of the |
167 |
software [brooks75mythical-man-month]_. |
software [brooks75mythical-man-month]_. |
168 |
|
|
207 |
require a more formal process for changes, as in Boehm's Spiral Model |
require a more formal process for changes, as in Boehm's Spiral Model |
208 |
of software development and enhancement [boehm88spiral-model]_. |
of software development and enhancement [boehm88spiral-model]_. |
209 |
On the outer edges of the system, new research is taking place and should |
On the outer edges of the system, new research is taking place and should |
210 |
not be hampered by process or documentation beyond the immediate |
not be hampered by requiring formal process or documentation beyond the |
211 |
|
immediate |
212 |
needs of the group members involved in the development of that particular part. |
needs of the group members involved in the development of that particular part. |
213 |
For this reason we have adopted some conventions from Extreme Programming, |
For this reason we have adopted some conventions from Extreme Programming, |
214 |
such as continuing analysis of design objectives along |
such as continuing analysis of design objectives along |
281 |
visually |
visually |
282 |
describe software architectures and constructs in diagrams |
describe software architectures and constructs in diagrams |
283 |
[booch-jacobson-rumbaugh98uml-user-guide]_. It was originally |
[booch-jacobson-rumbaugh98uml-user-guide]_. It was originally |
284 |
developed for descriptions on an abstract level (many constructs |
developed for descriptions on an abstract level (many constructs of it |
285 |
cannot be directly expressed in any programming language) |
cannot be directly expressed in any programming language) |
286 |
[booch-jacobson-rumbaugh98uml-user-guide-onpage-12]_, but the current |
[booch-jacobson-rumbaugh98uml-user-guide-onpage-12]_, but the current |
287 |
trend in research is to use it also on the concrete level, as to fully unify the |
trend in research is to use it also on the concrete level, as to fully unify the |
288 |
architectural documentation and program code: the program code might |
architectural documentation and program code: the program code might |
289 |
be generated from highly detailed diagrams |
be generated from highly detailed diagrams |
290 |
[harrison-barton-raghavachari00uml-to-java]_. |
[harrison-barton-raghavachari00uml-to-java]_, or diagrams may be produced |
291 |
Another use of UML is in reverse engineering, where |
directly from the source code |
|
diagrams may be produced from the source code |
|
292 |
[pierce-tilley02connecting-documentation-rose]_. |
[pierce-tilley02connecting-documentation-rose]_. |
293 |
|
|
294 |
In this article we focus on the more conventional use of UML |
In this article we focus on the more conventional use of UML |
296 |
architecture on a general level. |
architecture on a general level. |
297 |
UML can function as a common language for |
UML can function as a common language for |
298 |
communication within a software development team, and for this purpose |
communication within a software development team, and for this purpose |
299 |
human-drawn (non-autogenerated) diagrams that show the semantically meaningful |
we prefer human-drawn (non-autogenerated) diagrams that show the semantically |
300 |
features at the right level of abstraction are preferred: |
meaningful features at the right level of abstraction: |
301 |
|
|
302 |
"You draw diagrams to visualize a system from different |
"You draw diagrams to visualize a system from different |
303 |
perspectives, so a diagram is a projection into a system. |
perspectives, so a diagram is a projection into a system. |