314 |
The problem of two separate bodies of documentation |
The problem of two separate bodies of documentation |
315 |
=================================================== |
=================================================== |
316 |
|
|
317 |
In our software engineering project[gzz]_, as probably in most projects that use the Java programming |
In our software engineering project [gzz]_, as probably in most projects that use the Java programming |
318 |
language [java-ref]_, the software development documentation is |
language [java-ref]_, the software development documentation is |
319 |
divided into two major domains: the design documentation and |
divided into two major domains: the design documentation and |
320 |
Javadoc [friendly95javadoc]_. The design documents cover the most |
Javadoc [friendly95javadoc]_. The design documents cover the most |
873 |
:width: 16.9cm |
:width: 16.9cm |
874 |
:label: screenshot |
:label: screenshot |
875 |
|
|
876 |
Collage of screenshots from Gzz project documentation. |
A collage of screenshots from Gzz project documentation. |
877 |
|
|
878 |
a) blaa |
a) The "frontpage" of our design documentation. Objects with blue |
879 |
b) foo |
background are linked, the item describing the active document |
880 |
c) goo |
is marked with orange background and "BROKEN LINK" marks that |
881 |
d) liirum |
element is defined to be linked,but the target couldn't be found. |
882 |
|
b) Moved to "Frontend". The implicitly embedded diagram from the |
883 |
|
front page is included at the top of the page as 50% diminished |
884 |
|
version. The element describing active document page "Frontend" is |
885 |
|
in addition to orange background, also rounded with rough edge. |
886 |
|
c) Moved to "gzz.client" Javadoc package description page. Several |
887 |
|
implicitly embedded diagrams shows the package's context. |
888 |
|
d) Moved to "PEG: Viewtool". Diagrams are split in two by |
889 |
|
horizontal line. Below the line is the diagram itself. Above is |
890 |
|
listed the documentation pages, where the diagram is explicitly |
891 |
|
included. "PEG" stands for "Proposals for Enchancing Gzz" and |
892 |
|
it's crucial part of our design documentation for future |
893 |
|
improvements. |
894 |
|
|
895 |
Discussion |
Discussion |
896 |
========== |
========== |