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]

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]

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

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]

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

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]

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]

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]

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]

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

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]

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]

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]

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]

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 [»parnDL2_1986]