Topic: software documentation

topics > computer science > Group: programming

document preparation

descriptive naming
design documentation
design languages
document-centered system
ease of learning
examples of hypertext systems
flow diagrams and flow charts
help in UserInterface
literate programming
minimal manuals and guided exploration
open systems
program listing
programming style
source-rich system
understanding systems


Language documentation serves the dual role of tutorial and reference. Correct, annotated examples provide models for both naive and experienced users, while a self-indexing organization allows easy reference by the experienced user. Programming systems should have easy to use and easy to teach documentation. One of FORTRAN's goals was to be learned quicker than assembly language. Rapid learning gives a language widespread use through new programmers. (cbb 5/80)
Subtopic: importance of documentation up

Quote: documentation should be an integral part of design and coding [»hoarCA_1974]
Quote: avoid and detect errors by orderly and logical programs; rewrite if necessary and provide documentation [»wilkMV_1951]
Quote: the EDSAC group did not use flowcharts
Quote: Emacs includes a complete, interactive, self-documenting help system; allows effective use of Emac's many features [»stallRM6_1981]
Quote: programs define algorithms but they are difficult to read; documentation helps answer questions [»parnDL8_1971]
Quote: module decomposition produces many small modules; software module guide for completeness, convincing arguments, software maintenance [»parnDL3_1985]
Quote: a software engineer should understand a module's responsibilities without understanding its internal design; should easily identify relevant modules without looking at their components [»parnDL3_1985]

Subtopic: new user experience up

Quote: a manual should allow a new user to immediately articulate and pursue his or her own goals
Quote: need to locate proper keys before learning to activate commands [»adamKA7_1983]
Quote: warnings, cautions, and other crucial information should appear very early in a manual [»coopRG4_1982]
Quote: forced learners to read the introduction by placing it across the envelope's seal [»carrJM_1990]

Subtopic: formal documentation up

Quote: readable, precise documentation is required; e.g., as input to tools [»hoffDM_2001]
Quote: for information hiding, describe module structure by the roles played, the secrets held, or the facilities provided [»parnDL3_1985]
Quote: a module specification tells you how to use the module and what it must do

Subtopic: guided exploration up

Quote: presented a user's guide in annotated form to illuminate design principles and explain the motivations [»ledgH_1981]
Quote: computer users spontaneously engage in discovery learning by skipping and skimming; creates a guided exploration manual [»willTR4_1992]
Quote: explain system usage with a sample walkthrough; allows users to vary the sample to suit their needs [»shneB_1998]

Subtopic: effective usage up

Quote: a book on the customary and effective usage of Java

Subtopic: software documentation up

Quote: language documentation should be concise without ill-defined technical jargon [»wirtN3_1976]
Quote: technical information should be geared to the specific needs of its audience [»younG_1988]
Quote: an active review consists of questions to be answered using the documentation; mostly individual work; generated a wealth of comments [»hoffDM_2001]
Quote: a software manual should discuss creative use of the software [»adamKA7_1983]
Quote: document a program with a set of independent displays, a lexicon, and an index; each display gives specification, program, and specifications of invoked programs [»parnDL12_1994]
Quote: document program by displays that specify the program's function and specify the function of omitted sub-programs; short enough to understand [»parnDL5_1988]
Quote: investigated documentation formats for programs; individual differences had largest effect, natural language was least effective [»curtB2_1989]
QuoteRef: abraPW2_1976 ;;18 copied an example program
Quote: module guide for the A-7 OFP flight software [»parnDL3_1985]

Subtopic: API documentation up

Quote: document the API; write doc comments for exported classes, interfaces, constructors, methods, and fields [»blocJ_2001]
Quote: for documenting inherited classes, first flatten the class before using Eiffel's 'short' command [»meyeB10_1992]

Subtopic: graphical documentation up

Quote: a brief data structure description or half-page diagram was more helpful than detailed pseudocode or detailed flowchart [»shneB1_1982]
Quote: describing software requires more than a word processor; e.g., software literature uses graphics, tables, fonts [»joneTC4_1979a]
Quote: produce a coding sheet and diagram that specify all details of the coding; allocate storage counters to the computation; indicate prints, interpolations, and checks [»compHU_1946]

Subtopic: system documentation up

Quote: the operating instructions for a sequence tape include the switches, tapes, card feeds, card punch, typewriters, counters, checks, plugging, and rerun instructions [»compHU_1946]
Quote: programmer's manual for the Ferranti Mark I based on the Manchester "baby" machine [»turiA3_1951]

Subtopic: reference documentation up

QuoteRef: cbb_1973 ;;pl/n has an alphabetic manual
QuoteRef: simscrip_1971 ;; alphabetic manual with formats, description, examples simple to complex, and thorough notes excellent

Subtopic: extracted documentation up

Quote: Eiffel's 'short' command documents a class by extracting parameters, documentation, pre- and post-conditions [»meyeB10_1992]
Quote: MicroTool generates declarations for each data section and code and calling sequence for each flowchart; automatic updates [»elshJL1_1991]
Quote: every definition in Common Lisp includes on-line documentation strings; allows user to query a symbol without searching text [»tichWF11_1987]
Quote: each function in an Emacs library includes documentation for the help system [»stallRM6_1981]

Subtopic: self-documenting system up

Quote: a system is self-described if every component includes a description
Quote: use routines to document code; e.g., a descriptive name can document a short routine [»mccoS7_1998]
Quote: KMS includes a script language of nearly 800 commands; a KMS frame acts as a function with links as function calls; self-documenting [»akscRM11_1993]
Quote: latent specifications in text by naming conventions, assertions, etc.; e.g., lock.. and unlock.., free.. and release.. [»englD10_2001]
Quote: a list of questions that a readable program/system should answer [»goldA_1986]
Quote: a system has uniform closure if every component can access every other component, including their descriptions [»smitDR11_1985]
Quote: a true test of self-documenting design is whether its maintainability is maintained [»weinGM_1982]
Quote: relax the Law of Demeter by declaring acquaintance classes; documents dependencies [»liebKJ9_1989]

Subtopic: hypertext up

Quote: Hypertext useful for structuring documents and notes used during system development [»conkJ12_1987]
Quote: linear organization not useful for program documentation; either squeezed into margin or breaks up program flow [»conkJ9_1987]
Quote: programming, writing documentation, and building databases are all for producing a large, complex document [»mashJR_1976a]
Quote: ZOG used to manage the ZOG project; contained all documents, software, reports, schedules, etc. [»mccrDL10_1984]

Subtopic: documentation diverges from system up

Quote: main obstacle to changing Multics was updating system documentation [»corbFJ_1979]
Quote: with large systems, documentation, tutorials and system may diverge because documentation is cut when schedules fail [»belaLA_1979]
Quote: in programming, discoveries and requirements grow faster than code; can not be systematic or keep up with documention [»berrDM10_2002]
Quote: use pseudocode in design documentation; keep both versions consistent; use different programmers [»parnDL2_1986]

Subtopic: problems with documentation up

Quote: documentation written by groups with unique concepts, terms, and module organization; difficult for outsiders to read
Quote: errors in software user manuals: too much mechanics, too little meaning, few ties to user's abilities, little feedback, too technical [»adamKA7_1983]
Quote: software inspection is a double pain; requires documentation beforehand and inspection itself is painful; easily dropped [»berrDM10_2002]
Quote: documentators usually focus on the details that look difficult; but readers find that the basic structure is not obvious and the details are overwhelming [»parnDL12_1994]
Quote: compared notes about Turing's description of his universal machine; large individual differences in style and evaluations [»naurP4_1993]
Quote: little agreement about what makes an understandable explanation of Turing's universal computer [»naurP4_1993]
Quote: formal methods are less understandable than actual program text
Quote: in documentation, avoid stream of consciousness (write as think) and stream of execution (write as it happened); difficult to find information

Related Topics up

Group: document preparation   (8 topics, 180 quotes)
Group: hypertext   (44 topics, 786 quotes)

Topic: comments (23 items)
Topic: descriptive naming (29 items)
Topic: design documentation (43 items)
Topic: design languages (12 items)
Topic: document-centered system (12 items)
Topic: ease of learning (38 items)
Topic: examples of hypertext systems (25 items)
Topic: flow diagrams and flow charts (21 items)
Topic: help in UserInterface (33 items)
Topic: literate programming (16 items)
Topic: minimal manuals and guided exploration (44 items)
Topic: open systems (33 items)
Topic: program listing (14 items)
Topic: programming style (47 items)
Topic: source-rich system (27 items)
Topic: understanding systems (48 items)
Topic: writing
(32 items)

Updated barberCB 1/06
Copyright © 2002-2008 by C. Bradford Barber. All rights reserved.
Thesa is a trademark of C. Bradford Barber.