The Best of Creative Computing Volume 1 (published 1976)
Conduit Documentation Guideline
I . COVER LETTER
A cover letter should be supplied by the local Curriculum Coordinator as
supplementary, local documentation for any CONDUIT package. The purpose of such
a letter is to provide prospective network users with a realistic picture of
their relationship with CONDUIT in the event of the package's adoption and to
state the costs, availability, and procedures for acquiring any materials(texts,
card decks, magnetic tapes,
program listings,etc.) needed for that adoption. Any discussion of availability
should list in addition to the source repository other network centers and
computer types at which this package is supported. Any restrictions (such as
copyrights, etc.) on the reproduction and use of these materials should be
stated at this time as well as the caveat that although CONDUIT has attempted to
maximize the educational value and technical reliability of the programs, no
liability for errors in these materials, expressed or implied,
is assumed by the author(s), the source facility (NAME), or the CONDUIT
consortium. User's expectations of CONDUIT support (computer time, programming
aid, consulting services, etc.) should be specifically covered in terms of
extent, personnel and mechanics involved.
2. ABSTRACT
The author of each package should provide an abstract sufficient to serve
as an all purpose introduction to the computer-based curriculum package. The
abstract should contain the following items:
(a) Descriptive title
(b) Mnemonic or calling name
(c) Author(s) and original source
(d) Names and locations of any subsequent modifiers
(e) Summary of substantive content
(f) Statement of educational objectives
(g) Specifications of computer's instructional role
(h) Background requirements for instructors and students
(i) References (if available)
3. EDUCATIONAL DOCUMENTATION
The author of a computer-based curriculum package addresses in this type of
documentation the needs of faculty and student users. Topics covered should
include the following:
(a) Substantive aspects-theoretical background and disciplinary principles of
this computer-based package.
(b) Pedagogical significance-relationship of the educational objectives
stated in this material to.content and instructional techniques.
(c) Implementation considerations-suggestions for instructional management
within the classroom, the computing environment and the standard curriculum.
These topics could appear in separate single-purpose manuals (e.g., Teacher's
Guide, Student Manual, Programmer's Guide, Problems, etc.) or as a collective
write-up depending on the size and scope of the package being documented.
4. TECHNICAL DOCUMENTATION
Technical documentation involves those materials necessary for the
understanding by a potential user of how the courseware (e.g., program)
operates. Technical documentation should attempt to extricate that programming
documentation which is universal and transportable. in terms of information
content. from site-specific descriptions needed only for local usage. ln order
to clarify both the program logic and function. one needs:
(a) Explanation of the program's logical organization and the functions of any
discrete modules.
(b) Well-commented program listing.
(c) Descriptions of sample input such as test data and any program parameter
cards required.
(d) Listing of output generated by such sample input.
(e) Test problems and expected results.
(f) Description of program options and how to exercise them.
(g) Listing and explanation of program-generated messages.
(h) Glossary of variable names and special discipline oriented items.
(i) ltemization and descriptions of supporting programs, subroutines and
external files.
(j) Formats for parameter and data cards.
For each data set. the following information should be available:
(a) Description of file organization.
(b) File data item definitions.
(c) Indices to the data set.
(d) Security procedures, if any.
5. LOCAL DOCUMENTATION
Curriculum Coordinators should provide network users with instructions for usage
of CONDUIT materials at their
local computer center. Information classifiable as local (or site-dependent) is
necessary only if it differs from that which is provided as universal
documentation. Such information includes:
(a) Instructions and examples on how to use the local computer (JCL, deck
setup, typical file or program access, major operations.
(b) A setup example of how to access the program under consideration.
(c) A listing of the local version of the program and notations on its
significant differences from the universal model.
(d) Sample I/O for this version of the program.
(e) information on typical run times and related costs.
In addition an overall description in explicit terms of the current computing
environment should state:
(a) Operating system, release level/version. '
(b) Mode of usage (batch versus interactive).
(c) Storage devices required.
(d) Special peripheral device requirements (central site).
(e) Special terminal needs (user site).
(f) Common causes of program failure and error recovery.
(g) Any other locally pertinent information or comments on these materials.
6. REVIEWS
Material selected for dissemination through CONDUIT is first reviewed under the
direction of an appropriate discipline committee. Those packages receiving
positive reviews are included in the CONDUIT Library for undergraduate education
with solicited reviews comprising a final section of the documentations.
