Since we launched iDocIt! at Google Code in April this year we used it in many of our projects. In April we knew that the API-documentation created with iDocIt! would become more complete than classical documentations created with e.g. Javadoc. But we had just very simple and rough thoughts about how to organize the work with iDocIt!. This changed over the last months and this blog posting is aboutt the way it changed.
The Javadoc usage guidelines define that API-documentation is owned by programmers [1]:
[...]
Who Owns and Edits the Doc Comments
The doc comments for the Java platform API specification is owned by [added by the author of this posting] programmers. However, they are edited by both programmers and writers. It is a basic premise that writers and programmers honor each other's capabilities and both contribute to the best doc comments possible.[...]
But does this imply that the whole API-documentation is written by them? We believe not. Clements et al. described that there are many stakeholders of API-documentation (e.g. managers, architects, testers, developers and some more)[2, page 237 and following]. When designing iDocIt! we had the strong intuition that due to their interest in the documented content, they could contribute something to the documentation. But who could contribute what?
We realized that the (especially on the level of interfaces) the semantics of an operation are defined mainly with business or domain specific terms. Many programmers are not familiar with these terms and this is no surprise. They are responsible for writing stable, maintainable and performant code (which all results in minimized overall development and maintenance costs). So why should they describe the business meaning of an operation if someone else could do this in less time? From our experience interfaces within a software systems are defined and specified by the architect. The person having this role has to specify the semantics in any case somewhere. But the architect does not care about illegal arguments for the operation or other constraint violations. The developer is responsible for describing these aspects. And finally the tester specifies test cases as invocation examples. This principle is shown by the figure above. We propose to contribute this directly to the API-documentation in the code.
How to to it with iDocIt!? We are going to show this to you over the next three postings in this blog. The first posting will show the parts documented by the architect. The second deals with the developer's part and the third covers everything contributed by the tester. We are looking forward to your feedback :).
[1]: Sun Microsystems, Inc: How to Write Doc Comments for the Javadoc Tool, 2004
[2]: Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Robert Nord and Judith Stafford: Documenting Software Architectures, Addison Wesley, 2004
Keine Kommentare:
Kommentar veröffentlichen