Go up to Contents and organization of project final reports
Go forward to Reference manual
User's guide
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++, and STL or other generic libraries you assume).
- Thus the document should not have a title like
"Distributed Software Components Course 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.