[7.32] Documenting Programs - Texas Instruments TI-89 Tip List

[7.32] Documenting programs

Program documentation answers these questions about your programs:
1. What problem does the program solve?
2. How do I use the program?
3. How does the program get its results?
4. How can I change the program to better meet my needs?
Documentation is work and it takes time. For most programmers, documentation is a chore, and not
nearly as interesting as designing and coding. If you are just writing programs for yourself, the
documentation is obviously your own business. However, if you distribute your programs to others, I
assume you really want people to be able to use them. Some useful programs may be so simple that
they don't need any documentation, but I have seen any, yet.
The main goal of documentation is to answer the questions above, as quickly as possible for both you
and the user. While you may be rightfully quite proud of your program, the user probably does not
share your enthusiasm. The user needs to solve a problem, and it looks like your program might do it.
Your responsibility in creating the documentation is to meet the user's needs. Those needs can be
grouped in two broad categories: answering questions and giving warnings. Some of the questions are
obvious, such as: how do I install the program? how do I run it? how do I fix this error? The warnings
are less obvious but just as important. You need to inform the user as to side effects that might not be
obvious. Some examples of these side effects might be changing the modes, creating folders or
creating global variables.
Documentation is just writing. Clear writing is a skill which, like any other, takes practice and
commitment. The more you do it, the better (and faster) you will get. In the remainder of this tip, I give
some suggestions for creating usable documentation. The suggestions are organized around the four
questions that users have.
What problem does the program solve?
If you have written a program to solve a problem, you are quite familiar with the problem. It may be a
problem in your field of expertise that you solve every day. But other users don't necessarily have your
background. They might just be learning about the field. They might be unsure of the terminology and
solution techniques. To meet those users' needs, you must have a short, clear, complete description of
the problem.
How do I use the program?
Your documentation should answer these questions for the user:
! Does the program run on either the 89 or the 92+? Are there special versions for each calculator?
! Does the program require a specific version of the AMS?
! How much ROM does the program take?
! Can the program be archived?
! How do I install the program?
! How do I uninstall the program?
7 - 30