|
Software documentation is often published in separate volumes called
User's Guide, Reference Manual, and Design Document. Results of
testing software are not usually published outside of an
organization's development group, and (unfortunately for later
maintainers) may not be documented at all. For the projects for this
course, prepare a single document with the following sections:
- User's guide
- Reference manual
- Design issues
- Source code
- Test plan and results
The user's guide contains the user level documentation and may contain
tutorial material (such as extended discussion of examples), but for
purposes of this course, tutorial material is optional.
The complete source code of a software product is not usually
published, but in this case your project reports should include it.
It is required that the code be presented in the literate programming
style, using the Nuweb tool. The code that you compile and test
must be the code that is extracted from the Nuweb source file
for your project. You should submit your report containing the code
and the other sections in both hardcopy form (resulting from
running Nuweb source file -> nuweb
-> latex -> dvips -> laser printer,
or, better, Nuweb source file -> Pdfnuweb
-> pdflatex -> laser printer) and as an
email message containing only the single Nuweb source file.
The SGI web pages contain mainly overview and reference material, and
some discussion of design issues; they contain only minimal tutorial
material and lack any discussion of testing. They point to the code
but do not use literate programming in presenting the coding details.
The User's guide should begin with an overview section.
The overview section is a crucial part of the documentation and you
should make sure it really does give an overview. Issues in writing
a good overview include:
- Who is the intended audience.
- What is the right level of discussion for that audience, in the overview (you can change to a more detailed level
in the later sections).
- What terms need to be defined to convey the main points to
the intended audience.
For the project reports for this course, the intended audience is
not the course instructor.
- Aim for a broader audience such as the professional programming
community, or, more likely, limited to C++ programmers (I leave some
discretion here, but you should make clear how much knowledge of
programming, C++, STL or BGL you assume).
- Thus the document should not have a title like "Advanced
Programming Project Report"; instead it should be descriptive of the
library component(s) developed in the project.
- The documentation should not refer to earlier work on
the project such as preliminary or progress reports; most readers
won't care about the history of the project. You might include some
information such as results of preliminary experiments with compiler
portability or performance, but only if it helps justify design
decisions of your final software (so it probably goes in the design
document if it is included at all).
This is one of the most difficult problems of technical writing; it is
tempting to dive into low level details in the overview long before
the reader is ready for them. This can also be a problem in tutorial
material (if any); you must introduce details a few at a time or else
the reader will be confused.
One crucial issue is how much, if any, to say about design
decisions in the overview. As a general rule, discuss design
decisions in the overview only to the extent you believe that doing
so will help convince your audience it is worth trying your
software. Overviews of STL, for example, generally include discussion
of many design decisions as part of the explanation of the advantages
of generic programming.
This will depend on your intended audience;
the more background you assume, the more you restrict your audience,
but spending a lot of space defining terms may turn off readers who
are already knowledgeable.
After the overview, the User's Guide often contains tutorial material
of various forms, particularly examples of use of the software and
discussions of pitfalls to avoid. Writing good tutorials is important
but is mostly beyond the scope of this project. Spend time on this
part only if you have everything else completed and polished.
In How to use the STL
documentation note the descriptions of
the format of concept pages, of type pages, and of function pages. You
should take these as guidelines for writing the reference manual part
of the documentation for your project.
In this section describe the key design decisions. This includes
interface and abstract semantics design decisions,
and why particular algorithms and data structures were chosen, versus
alternatives. Remember that this documentation is not for the end-user,
and thus may be more technical than the User's Guide.
As much as possible, separate the design issues into an
abstraction level and an implementation level:
- The abstraction level design issues concern the interface,
semantics, and performance requirements.
- The implementation level design issues concern the
choice of internal algorithms and data structures that meet the
abstraction level requirements. Do not discuss details that would be
obvious from reading the code, but if you have used nonobvious
optimizations in your code then either here or the
next section (source code) is the place to describe them.
Occasionally you may need to refer to some of the
implementation issues in justifying your abstraction level design
choices.
Some further points: - It may be useful to make comparisons to other libraries or
software packages. Though not essential, such comparisons can help
readers who might have knowledge of other software put your library in
perspective. Avoid comparisons to software that is not widely known,
since only a few people would be able to appreciate the comparison.
Also avoid denigrating competing software or design decisions with
phrases like "an awful hack"; keep your comparisons on a technical
basis.
- Give a detailed rationale for your design decisions if you think it
will either (1) help convince readers to use your software, or (2)
help future maintainers, re-implementors, or extenders of your software
to avoid making other design choices that you know are inferior
(because you tried them, or rejected them on the basis of careful
analysis).
- By the same token, avoid rationalizing decisions for which
you have little supporting evidence; it's better simply to say that other
decisions were possible but were not explored.
As mentioned above, you are required to present the complete source
code using the literate programming style. In some cases you may find
it easier to present design decisions and source code if you
combine them in a single section. This is permitted.
Keep in mind the flexibility the literate programming style permits:
you can present the most important parts of your code first, followed
by the details, assembling the parts into an order acceptable to the
compiler in an "overview" or "outline" part (which can come either
before or after the other parts). You may even relegate nitty-gritty
details to an appendix so they don't make the main discussion
too long.
As mentioned in the initial project assignment, testing should be
extensive, including checking correctness of small cases, including
boundary cases such as empty sequences, and measuring performance of
large randomly generated inputs of a variety of sizes (possibly up to
100,000 or a million elements, depending on the algorithms or data
structures involved).
- Correctness for large inputs should also be checked, using an
acceptance routine. For example, to check a sort routine, use an
acceptance routine that checks to see if the result is in order, or
better, checks to see if it is exactly the same output as that from
another sort routine known to be correct. For this to work, the
benchmark routine must have the same stability properties as the
routine under test.
- In timing fast algorithms on moderate size inputs (a few
thousand elements) you may need to repeat some number of trials of the
algorithm, record the total time, and divide that by the number of
trials, to get an accurate average time. Note that this is different
from (and usually will be more accurate than) timing each trial,
totaling the times, and dividing by the number of trials.
- Be sure to say which platforms you have run your tests on,
giving the hardware platform (including processor speed) and compiler
(including version and option selections, especially the optimization
level). If you have run tests with
more than one platform/compiler combination, make clear which of
your test results correspond to which combination.
- Pay attention to grammar, spelling, and punctuation.
Any problems in these areas can distract readers from your
main message, or, worse, drive them away entirely.
- Read, or reread, Strunk and White, The Elements of Style.
It's short, pleasant to read, and always helpful.
- Always run your documents through a spelling checker
before submitting them to anyone else to read.
- Remember also to check manually for problems that a spelling
checker can't detect (see below).
- Often it's difficult to see grammatical errors in your own
writing, even if you know the rules, so have someone else proofread it too.
- Document formatting errors can also be distracting. See the
LaTeX section for help in avoiding common errors.
- Write clearly and simply, and maintain a level of formality
of style. In a team project, different parts of the report will typically
be drafted by different members of the team, with inevitable
differences in style. One team member should take the role of editor,
resolving such differences to achieve a single writing style in the
final document.
Ode To My Spell Chequer
Author Unknown
I have a spelling chequer,
It came with my PC.
It plainly marks for my revue,
Miss takes I can not sea.
I've run this poem threw it,
I'm sure your please too no.
Its letter perfect in it's weigh,
My chequer tolled me sew.
|