A. Oram
ABSTRACT
Computer documentation reflects the underlying structures and relationships within computer systems. Therefore, successful documentation depends on understanding and interpreting these structures and relationships, not on superficial improvements in writing style, format, presentation philosophy, or technical medium.
This paper proposes that the research and writing of documentation be driven by the structure of the software. The paper identifies tasks to be performed on the design side of the software, and on the documentation side.
The most formal and technical part of this paper covers the responsibilities of the engineers, and provides writers with a proposal they can present to their reviewers. This section lists the basic categories of features that engineers must cover (flags, counters, identifiers, table entries, and raw data), as well as what to document for each feature. It is the engineers' responsibility to provide a context for each feature on the system, showing how it would be used in real life.
Based on this feature-by-feature information, writers must build examples and procedures of gradually increasing complexity. The resulting documents contain immediately applicable information, and are easy to verify and review.
Index Terms
- Sentence first, verdict afterward: finding the prerequisites for good computer documentation
Recommendations
Documentation threads - presentation of fragmented documentation
In this paper, we introduce a means for presenting fragmented documentation through a concept called documentation threads. A documentation thread presents a number of documentation fragments specified by the programmer and can guide a documentation ...
Finding good feedback documents
CIKM '09: Proceedings of the 18th ACM conference on Information and knowledge managementPseudo-relevance feedback finds useful expansion terms from a set of top-ranked documents. It is often crucial to identify those good feedback documents from which useful expansion terms can be added to the query. In this paper, we propose to detect ...
Computer model documentation
WSC '78: Proceedings of the 10th conference on Winter simulation - Volume 1Recent studies and surveys have concluded that, in general, the documents produced to support the understanding and use of computer models are inadequate. This paper describes some of the issues and concerns of computer model documentation and proposes ...
Comments