Rob Kremer
Practical Software Engineering
- A formal development methodology must be used for contractors to be
monitored by buyers (or project managers, etc.). Formal documents must be used
for this.
- Internal (in-house) software development also needs a formal development
methodology.
- Each of the boundaries between development phases should be clearly
defined by issuing a document. This should state what has been accomplished
during the preceding phase and present or reference all relevant documents.
- The issue of each document should be preceded by a design review which
aims at evaluating and validating the draft of the document.
- The best procedure is to have the validation done as each phase is
completed. The results of the validation should be reported in a written
document.
Poor quality documentation is the second most common
problem reported in software maintenance (the first is user demands for
enhancements and extensions)
- Request for proposal *
- Proposal document *
- Any studies, papers, reports which support items 1 and 2 **
- Preliminary specifications
- Preliminary design document (memo plus OMT diagrams, flowchart, pseudo-code, etc.)
- Detailed specifications
- Detailed design document (formal report plus OMT diagrams, flowcharts, pseudo-code, etc.)
- Documents supporting unit testing (test plans, lists of test cases and
expected results, lists of errors, programmers' notebooks)
- Documents specifying how configuration control is to be performed.
- Documents supporting integration test (test plans, list of test cases and
expected results, lists of errors, programmers' notebooks, computer records)
- Forms describing each error by number and how it was discovered, the
diagnosed cause of the error, and how it was corrected
- Acceptance test plans and results
- Field test plans, operational notebooks, and results
- Documents resulting from design reviews or management decisions
- Any related specifications and design guides.
* In the case of an
in-house project, memos of direction and intent may serve the same role as
these documents.
** Copies of the contract; any quality assurance plans and documents;
engineering studies of reliability, memory requirements, processing time, or
prior engineering or feasibility studies, etc.
M. Rettig, Communications of the ACM, 34(7), 1991 pp.19-24.
Most documentation is written by technicians, yet technicians frequently
complain about it.
- tutorial
- task-oriented users guide
- alphabetical reference to commands
- pictorial guide to windows, icons, tool palettes
- reference cards
- specialized guides to getting started, installation etc
- hypertext style of on-line help
- Impatient to start
- Skip around manuals and on-line documents
- Discouraged by large manuals
- Provides only essential information
- Only basic topics
- No repetition, summaries, reviews etc
- No welcome etc
- Modularized into small chunks directed at user's actual work
- Task oriented documentation helps people get things done
Software
designers and technical writers should interact throughout the design
lifecycle.
Documentation should be viewed as a creative challenge to provide information
for end users.
Manuals should:
- Provide factual knowledge on all aspects of the software and its use
- use varies for user, operator etc
- Provide in depth information -- may be separate packages
- full reference manuals with cross-reference lists
- user reference guide
- systems manual
- installation manual
- operator procedures
- maintenance guide
- Provide fast access to information
- people do not read manuals cover to cover
- manuals should be well organized, accurate and consistent
- Accommodate levels of knowledge
- start with basic levels and go on to advanced
- Define all terms
- Cross-reference between phase documents
- Group related material
- Provide an index
1. Introduction
- product philosophy
- hardware/software environment
- how to start product (incl. prepare for start)
- how to use manual--progressive steps
2.-k. Successive learning steps
- steps in logical order of using and learning, not alphabetically
- most basic features or usage first
- increasing sophistication
- goal of learning in each section
- whole work units
- error messages and how to deal with them examples
Appendices.
A.1. glossary of terms
A.2. index
A.3. short alphabetical reference section of commands (maybe as a card)
A.4. collected error messages
1. Introduction
- product overview and philosophy
- product component/feature overview and interfaces
- state transitions between system states
- hardware/software environment, interfaces
- structure of manual
2.-k. Components and features
- (in alphabetic order) description of commands (features) in detail
with all default parameters
- error messages
- examples
Appendices
A.1. error messages, explanations, effects, system status, possible actions.
Cross-reference to section that explains system component or feature.
A.2. index
A.3. short, alphabetically ordered reference card for commands.
R. Williams, Peachpit Press 1990.
- Underlining: Don't underline. Underlining is for typewriters;
italic is for professional text.
- Capitals: Very rarely (almost never) use all capital letters.
- Kerning: Kerning is the process of removing small units of space
between letters in order create visually consistent letter spacing. Adjust the
space between letters according to your sensitive visual perception.
- Fonts: Any font with a city name has been designed for the
ImageWriter. These are bit-mapped fonts. Exceptions are New York, Geneva,
Monaco.
- Tabs and Indents: Many people try to use the spacebar to line up
words or numbers. Use those tabs and first-line indents regularly and properly.
Never use the space bar to align text.
- Widows and Orphans: When a paragraph ends and leaves the last line
at the top of a page, that last line is called a widow. An orphan is a heading
or first line of a paragraph left at the bottom of a page. Never leave windows
and orphans.
- Hyphenations and Line breaks: Avoid too many hyphenations in a
paragraph, avoid stupid hyphenations, never hyphenate a heading and break lines
sensibly.
- Leading or linespace: Linespacing within a paragraph should be
consistent. If even one letter or word is larger than the rest in a paragraph,
the linespacing adjusts to fit the larger characters, creating uneven spacing
that looks awkward.
- Justified text: Justify text only if the line is long enough to
prevent awkward and inconsistent word spacing. Ragged right is more often
correct.
- Hanging the punctuation: Always attach punctuation marks to the
text. This prevents a . or , on a separate line.
- Serif and Sans Serif: Type can generally be classified into two
major groups; serif and sans serif. Serif type is more readable and is best for
text; sans serif type can be used for headlines.
- Establish what documentation currently exists in the organization.
Consider the job of each user in turn. Decide whether he will require a user's
guide to equipment operation, a user's guide to the system or any other
documentation.
- Decide which of the following methods of providing documentary support is
to be used for the user documentation:
- paper-based manual;
- paper-based circulars;
- expert system;
- help facilities;
- computer-based documentation.
- Use your own internal standards for producing the documentation. If no
standards exist, decide on the format, style, presentation and method of update
to be used. Get the user to assist in producing the documentation or, failing
this, to vet it as it is produced.
- Get some of the potential users to try out the documentation and note
their reactions and comments. Make any necessary modifications and try it out
on the users again. Continue this process until the documentation is
satisfactory.
- Set up procedures that will enable users to suggest changes to the
documentation. Display these procedures in a prominent position, either in the
documentation or on the documentation workstation.
- Establish which job title has responsibility for making amendments to the
documentation.
- For paper-based documentation, establish which job title has
responsibility for the physical update of the manuals.
Practical Software Engineering, Department of Computer Science
Rob Kremer