12 |
OTOH, talking more about us makes it more personal but may make it |
OTOH, talking more about us makes it more personal but may make it |
13 |
also seem less relevant to others' efforts. |
also seem less relevant to others' efforts. |
14 |
|
|
15 |
|
SUGGESTED RESOLUTION: "Setting of problem" should be about us: |
16 |
|
describe exactly what docs **we** have. Everything else |
17 |
|
should be more general, and we should point out that |
18 |
|
this situation is probably not uncommon. |
19 |
|
|
20 |
- do we need critics against graphical coding with UML somewhere? |
- do we need critics against graphical coding with UML somewhere? |
21 |
This could be found at least in articles supporting |
This could be found at least in articles supporting |
22 |
domain spesific languages (which may be used for graphical coding) |
domain spesific languages (which may be used for graphical coding) |
23 |
|
|
24 |
|
RESOLVED: Probably not: graphical languages have not taken |
25 |
|
off to a sufficient degree that we should really have to criticize |
26 |
|
them. |
27 |
|
|
28 |
|
- How should we discuss WYSIWYG, WYSIAYG for reST &c? Someone will surely ask about that, |
29 |
|
|
30 |
|
PARTIAL RESOLUTION: |
31 |
|
|
32 |
|
- proprietarity |
33 |
|
- versioning much worse |
34 |
|
- users = programmers --> used to editing text and compiling |
35 |
|
- lack of good, **extensible** tools |
36 |
|
|
37 |
|
- why even outdated but well simplified diagram |
38 |
|
is better than too detailed, automaticly up-to dated |
39 |
|
and reverse engineered diagram. |
40 |
|
|
41 |
|
|
42 |
Introduction |
Introduction |
43 |
============ |
============ |
44 |
|
|
166 |
Setting of problem |
Setting of problem |
167 |
================== |
================== |
168 |
|
|
169 |
Javadoc |
In our project, ..., |
170 |
|
the software engineering documentation |
171 |
|
is divided into two classes: |
172 |
|
|
173 |
- fully generated documentation from development |
The two types of documentation are complementary. |
|
project's java source code |
|
174 |
|
|
175 |
- easy to find a given class, easy to check methods |
+----------------------------------------+----------------------------------------------+ |
176 |
|
| Design docs | Javadoc | |
177 |
|
+----------------------------------------+----------------------------------------------+ |
178 |
|
| | | |
179 |
|
| - good overall picture. | - easy to find a given class, | |
180 |
|
| | easy to check all methods | |
181 |
|
| | | |
182 |
|
| - little detail, | - detailed | |
183 |
|
| | | |
184 |
|
| - may be slightly outdated at | - methods and classes *always* up to | |
185 |
|
| any particular time. | date (generated from source), | |
186 |
|
| | doc comments also usually | |
187 |
|
| | | |
188 |
|
| - hard to find explanations | - no overall picture of classes' roles | |
189 |
|
| for a particular class. | | |
190 |
|
| | | |
191 |
|
| - UML diagrams | | |
192 |
|
| | | |
193 |
|
| - written and organized by humans | | |
194 |
|
| | | |
195 |
|
+----------------------------------------+----------------------------------------------+ |
196 |
|
|
197 |
|
Javadoc |
198 |
|
|
199 |
|
- fully generated documentation from javadoc comments |
200 |
|
of each class and method in the java source code |
201 |
|
|
202 |
+ the javadoc output filestructure follows the |
+ the javadoc output filestructure follows the |
203 |
hierarchical tree structure of java packages and classes |
hierarchical tree structure of java packages and classes |
204 |
|
|
205 |
- the location in class-tree is well shown everywhere in |
+ hypertext disorientation problem still exists |
|
javadoc, but the role of single class or package in |
|
|
developing software remains unknown |
|
|
|
|
|
+ hard to get overall picture. |
|
|
+ hypertext disorientation problem still exists |
|
206 |
|
|
207 |
Edwards, D., & Hardman, L. (1989). Lost in Hyperspace: |
Edwards, D., & Hardman, L. (1989). Lost in Hyperspace: |
208 |
Cognitive Mapping and Navigation in a Hypertext Environment. |
Cognitive Mapping and Navigation in a Hypertext Environment. |
210 |
Practice (105-125), Oxford: Intellect Limited. |
Practice (105-125), Oxford: Intellect Limited. |
211 |
(code in JYU-lib: "MK TIE HYPER") |
(code in JYU-lib: "MK TIE HYPER") |
212 |
|
|
|
- because doc is generated from source, the class, method, field |
|
|
names and their inline documentation are always up-to-date(!!) |
|
213 |
|
|
214 |
Architectural docs with UML diagrams: |
Architectural docs with UML diagrams: |
215 |
|
|
216 |
|
|
217 |
|
|
218 |
|
|
219 |
- diagrams are from human to human |
- diagrams are from human to human |
220 |
|
|
221 |
+ we don't wan to generate diagrams from the code or generate |
+ we don't wan to generate diagrams from the code or generate |
223 |
+ generated diagrams are too detailed to be beneficial |
+ generated diagrams are too detailed to be beneficial |
224 |
+ basic architectural diagrams should be done before code anyway |
+ basic architectural diagrams should be done before code anyway |
225 |
|
|
|
- good overall picture. |
|
226 |
|
|
|
- little detail, |
|
|
|
|
|
- may be slightly outdated at any particular time. |
|
227 |
|
|
|
+ why even outdated but well simplified diagram |
|
|
is better than too detailed, automaticly up-to dated |
|
|
and reverse engineered diagram. |
|
228 |
|
|
|
- distinct from the javadoc, hard to find explanations |
|
|
for a particular class. |
|
229 |
|
|
230 |
+ and if documentation is outdated some particular classes |
+ and if design documentation is outdated some particular classes |
231 |
maybe don't even exist anymore! |
maybe don't even exist anymore! |
232 |
|
|
233 |
- these cover the most relevant parts from the architecture |
- these cover the most relevant parts from the architecture |
234 |
and the code |
and the code |
235 |
|
|
236 |
The two types of documentation are complementary. |
- Include PEGs: possibly not-yet accepted or not-yet implemented proposals |
237 |
|
for architectural changes. |
238 |
|
|
239 |
"Obvious" question: can we increase the overall value by |
"Obvious" question: can we increase the overall value by |
240 |
interconnecting the two? |
interconnecting the two? |