182 |
.. Javadoc has plenty of unhierarchical links, but they are not meaningful, |
.. Javadoc has plenty of unhierarchical links, but they are not meaningful, |
183 |
they don't give the documentation any structure. |
they don't give the documentation any structure. |
184 |
|
|
185 |
The role of documentation in Software Engineering |
In the following sections, we first discuss the role of documentation |
186 |
|
in software engineering, then bring the problem of the distinct |
187 |
|
documentation bodies into focus and present our solution and |
188 |
|
its implementation. Finally, we discuss our practical use of the tool |
189 |
|
and conclude. |
190 |
|
|
191 |
|
Documentation in Software Engineering |
192 |
================================================= |
================================================= |
193 |
|
|
194 |
|
Software engineering process |
195 |
|
---------------------------- |
196 |
|
|
197 |
In their article "A rational design process: how and why to fake it" |
In their article "A rational design process: how and why to fake it" |
198 |
[parnas-clements86rational]_ Parnas and Clements argue that rational |
[parnas-clements86rational]_ Parnas and Clements argue that rational |
199 |
software design process is not generally possible, but acceptable |
software design process is not generally possible, but acceptable |
282 |
intercommunication within our group, we believe manually made human |
intercommunication within our group, we believe manually made human |
283 |
abstracted documentation serves our purposes best. |
abstracted documentation serves our purposes best. |
284 |
|
|
285 |
|
UML |
286 |
|
--- |
287 |
|
|
288 |
|
The Unified Modeling Language (UML) is the standard way to visually |
289 |
|
describe software constructs in diagrams |
290 |
|
[booch-jacobson-rumbaugh98uml-user-guide]_. It was originally |
291 |
|
developed for descriptions on an abstract level (many constructs |
292 |
|
cannot be directly expressed in any programming language) |
293 |
|
[booch-jacobson-rumbaugh98uml-user-guide-onpage-12]_, but the current |
294 |
|
trend in research is to use it also on the concrete level, as to fully unify the |
295 |
|
architectural documentation and program code: the program code might |
296 |
|
be generated from highly detailed diagrams |
297 |
|
[harrison-barton-raghavachari00uml-to-java]_. |
298 |
|
Another use of UML is in reverse engineering, where |
299 |
|
diagrams may be produced from the source code |
300 |
|
[pierce-tilley02connecting-documentation-rose]_. |
301 |
|
|
302 |
|
In this article we focus on the more conventional use of UML |
303 |
|
to plan and document software |
304 |
|
architecture on a general level. |
305 |
|
UML can function as a common language for |
306 |
|
communication within a software development team, and for this purpose |
307 |
|
human-drawn (non-autogenerated) diagrams show the semantically meaningful |
308 |
|
features at the right level of abstraction are preferred: |
309 |
|
|
310 |
|
"You draw diagrams to visualize a system from different |
311 |
|
perspectives, so a diagram is a projection into a system. |
312 |
|
For all but the most trivial systems, a diagram represents an elided |
313 |
|
view of the elements that make up a system." |
314 |
|
[booch-jacobson-rumbaugh98uml-user-guide-onpage-24]_ |
315 |
|
|
316 |
|
.. (could other stakeholders be identified and described to some |
317 |
|
extent somewhere? it might be interesting to think also towards |
318 |
|
users/customers, who in some methods (ways of using XP) control |
319 |
|
use cases themselves) |
320 |
|
|
321 |
|
.. UML is easier to read than write. Also, non-programmers often |
322 |
|
don't have the insight needed to directly take part in designing |
323 |
|
(even in use cases)? |
324 |
|
|
325 |
|
|
326 |
|
.. some references to the screenshots here? |
327 |
|
|
328 |
|
|
329 |
The problem of two separate pieces of documentation |
The problem of two separate pieces of documentation |
330 |
=================================================== |
=================================================== |
331 |
|
|
414 |
|
|
415 |
The design for bi-directional navigation |
The design for bi-directional navigation |
416 |
======================================== |
======================================== |
|
|
|
|
UML |
|
|
--- |
|
|
|
|
|
The Unified Modeling Language (UML) is the standard way to visually |
|
|
describe software constructs in diagrams |
|
|
[booch-jacobson-rumbaugh98uml-user-guide]_. It was originally |
|
|
developed for descriptions on an abstract level (many constructs |
|
|
cannot be directly expressed in any programming language) |
|
|
[booch-jacobson-rumbaugh98uml-user-guide-onpage-12]_, but the current |
|
|
trend in research is to use it also on the concrete level, as to fully unify the |
|
|
architectural documentation and program code: the program code might |
|
|
be generated from highly detailed diagrams |
|
|
[harrison-barton-raghavachari00uml-to-java]_. |
|
|
Another use of UML is in reverse engineering, where |
|
|
diagrams may be produced from the source code |
|
|
[pierce-tilley02connecting-documentation-rose]_. |
|
|
|
|
|
In this article we focus on the more conventional use of UML |
|
|
to plan and document software |
|
|
architecture on a general level. |
|
|
UML can function as a common language for |
|
|
communication within a software development team, and for this purpose |
|
|
human-drawn (non-autogenerated) diagrams show the semantically meaningful |
|
|
features at the right level of abstraction are preferred: |
|
|
|
|
|
"You draw diagrams to visualize a system from different |
|
|
perspectives, so a diagram is a projection into a system. |
|
|
For all but the most trivial systems, a diagram represents an elided |
|
|
view of the elements that make up a system." |
|
|
[booch-jacobson-rumbaugh98uml-user-guide-onpage-24]_ |
|
|
|
|
|
.. (could other stakeholders be identified and described to some |
|
|
extent somewhere? it might be interesting to think also towards |
|
|
users/customers, who in some methods (ways of using XP) control |
|
|
use cases themselves) |
|
|
|
|
|
.. UML is easier to read than write. Also, non-programmers often |
|
|
don't have the insight needed to directly take part in designing |
|
|
(even in use cases)? |
|
|
|
|
|
|
|
|
.. some references to the screenshots here? |
|
|
|
|
417 |
XXX Hypertext blaablaa something... |
XXX Hypertext blaablaa something... |
418 |
----------------------------------- |
----------------------------------- |
419 |
|
|