166 |
Setting of problem |
Setting of problem |
167 |
================== |
================== |
168 |
|
|
169 |
In our project, ..., |
In our project, as probably in most projects that use Java, |
170 |
the software engineering documentation |
the software engineering (not user!) documentation is divided into two classes: |
171 |
is divided into two classes: |
design documentation and Javadoc. |
172 |
|
|
173 |
Javadoc |
The design documents cover the most important architectural features |
174 |
|
and are written either before coding (for design) or after (for exposition |
175 |
- fully generated documentation from javadoc comments |
of the architecture). |
|
of each class and method in the java source code |
|
|
|
|
|
+ the javadoc output filestructure follows the |
|
|
hierarchical tree structure of java packages and classes |
|
|
|
|
|
Architectural docs with UML diagrams: |
|
|
|
|
|
|
|
|
|
|
176 |
|
|
177 |
- diagrams are from human to human |
- diagrams are from human to human |
178 |
|
|
181 |
+ generated diagrams are too detailed to be beneficial |
+ generated diagrams are too detailed to be beneficial |
182 |
+ basic architectural diagrams should be done before code anyway |
+ basic architectural diagrams should be done before code anyway |
183 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
184 |
+ and if design documentation is outdated some particular classes |
+ and if design documentation is outdated some particular classes |
185 |
maybe don't even exist anymore! |
maybe don't even exist anymore! |
186 |
|
|
|
- these cover the most relevant parts from the architecture |
|
|
and the code |
|
187 |
|
|
188 |
- Include PEGs: possibly not-yet accepted or not-yet implemented proposals |
- Include PEGs: possibly not-yet accepted or not-yet implemented proposals |
189 |
for architectural changes. |
for architectural changes. |
190 |
|
|
191 |
|
Javadoc, on the other hand, is |
192 |
|
|
193 |
|
- fully generated documentation from javadoc comments |
194 |
|
of each class and method in the java source code |
195 |
|
|
196 |
|
+ the javadoc output filestructure follows the |
197 |
|
hierarchical tree structure of java packages and classes |
198 |
|
|
199 |
|
|
200 |
|
|
201 |
|
|
202 |
|
|
203 |
|
|
204 |
The two types of documentation are complementary, as demonstrated in the following table.. |
|
205 |
|
|
206 |
|
The two types of documentation are complementary, as demonstrated in the following table: |
207 |
|
|
208 |
+----------------------------------------+----------------------------------------------+ |
+----------------------------------------+----------------------------------------------+ |
209 |
| Design docs | Javadoc | |
| Design docs | Javadoc | |
226 |
| - written and organized by humans | | |
| - written and organized by humans | | |
227 |
| | | |
| | | |
228 |
+----------------------------------------+----------------------------------------------+ |
+----------------------------------------+----------------------------------------------+ |
|
"Obvious" question: can we increase the overall value by |
|
|
interconnecting the two? |
|
229 |
|
|
230 |
Architectural docs easily left in the dark reaches of the filesystem, |
Problems with the docs: |
|
not used as often as javadocs. |
|
231 |
|
|
232 |
+ hypertext disorientation problem still exists |
+ Architectural docs easily left in the dark reaches of the filesystem, |
233 |
|
not used as often as javadocs. - refs about documents left unused because |
234 |
|
hard to find? |
235 |
|
|
236 |
|
+ hypertext disorientation problem still exists with javadoc |
237 |
|
|
238 |
Edwards, D., & Hardman, L. (1989). Lost in Hyperspace: |
Edwards, D., & Hardman, L. (1989). Lost in Hyperspace: |
239 |
Cognitive Mapping and Navigation in a Hypertext Environment. |
Cognitive Mapping and Navigation in a Hypertext Environment. |
242 |
(code in JYU-lib: "MK TIE HYPER") |
(code in JYU-lib: "MK TIE HYPER") |
243 |
|
|
244 |
|
|
245 |
|
"Obvious" question: can we increase the overall value by |
246 |
|
interconnecting the two? |
247 |
|
|
248 |
Design |
Design |
249 |
====== |
====== |
250 |
|
|