""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
ADD COMMENTS, MANUALS, & TUTORIALS TO EACH APPLICATION
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
PRODUCT : R:BASE VERSION : 3.1
CATEGORY : PROGRAMMING SUBCATEGORY : TOOLS
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
From Robert Saunders, Business Systems Consulting, 59 E. Linden Ave.,
Suite B7, Englewood, NJ 07631. You can reach Bob at 201-568-3919.
Each R:BASE application should have internal documentation to benefit
those who develop and maintain the application and external
documentation to benefit those who use the application.
Using tools provided in R:BASE 3.1, you can create useful
documentation with a minimum time investment.
Internal Documentation
""""""""""""""""""""""
Internal documentation is vital because in six months, or even two
weeks, you'll be back trying to figure out what you did, and how you
did it. Internal documentation includes descriptions and explanations
for each table, column, form, and report as well as comments in R:BASE
programs.
I frequently take over a client's system that was originally set up by
someone else. Usually it was a consultant who won the lottery and
moved to Tahiti or some such story. If the application has internal
documentation, my job is easier, so it costs the client less money.
At a minimum, internal documentation should include these items:
o Descriptive names for variables, tables, columns, forms, and
reports.
o Explanations attached to each table, column, form, and report.
o Liberal comments in macros, entry/exit procedures (EEPs), and
other R:BASE programs. You should require application developers
to place explanatory comments, enclosed in *(---), every few
lines in all R:BASE programs. Comments in the code will save you
hours of work when you want to make changes. Forget that old saw
about comments slowing down your program. It barely makes a
difference.
External Documentation
""""""""""""""""""""""
Most systems I see have no user's manual, tutorial, or other help
screens - nothing is written down. People pay consultants thousands of
dollars for such systems. When the person trained to use it leaves the
organization, there's nothing to show the next person how to use it.
You should always require documentation, both internal and external,
with every application. Would you buy R:BASE without a manual?
Taking Snapshots of the Screen
""""""""""""""""""""""""""""""
Using R:BASE 3.1 features, it's easy to put together a simple manual
and tutorial. Use the SNAP command or press [Ctrl-F1] to take
snapshots of the screen at each point in the program. A snapshot saves
a screen image in a file.
At any point in an application, whether you're developing it or using
it, you can press [Ctrl-F1], and a menu will pop up. Choose "Take a
Snapshot," and R:BASE will ask you to name the snapshot file. That's
all there is to it.
Snapshots taken by pressing [Ctrl-F1] can be edited, but snapshots
taken with the SNAP command can't. This is because SNAP adds screen
characters such as colors to the file. Use the DISPLAY command to view
shapshots taken by SNAP.
Take Snapshots of Everything
""""""""""""""""""""""""""""
Press [Ctrl-F1] to take snapshots of forms, reports, and menus and
store them in a set of files. Snap them empty and snap them when they
contain sample data. To view or print the snapshot files, use RBEDIT
or DISPLAY. For example, the following prints a snapshot file
(TRANFORM.SNP):
OUTPUT PRINTER
DISPLAY tranform.snp
OUTPUT SCREEN
You could use RBEDIT to edit the snapshots to add comments, but it
might be better to print them as is, and then hand write the comments.
That way it will be obvious what's part of the form and what's a
comment.
Also take snapshots of all the menu actions in an Application EXPRESS
application. To do this, start Application EXPRESS, and choose the
application as if you were going to modify it. Then press [Shift-F3]
for the menu. Choose the menu you want, and then press [Shift-F3]
again. The menu actions will appear. Press [Ctrl-F1], and take a
snapshot. Then go on to the next menu and do the same until you've
snapped all the actions associated with each menu. Use these snapshots
and the snapshots of the actual menus to make the manual.
Making a Manual
"""""""""""""""
To read snapshot files taken by [Ctrl-F1], you can use any text editor
or a word processor set to text (DOS, non-document, or ASCII) mode.
To combine the files using RBEDIT, enter the SET BELL OFF command at
the R> prompt. Then start RBEDIT, and bring up the first snapshot
file. Go to the end of that file by pressing the [End] key. Then press
[Ctrl-F1]. From the menu box, choose "Play back a Script," and enter
the name of the snapshot file you want to merge. Continue until all
the snapshot files are combined. To insert a snapshot file into the
middle of a file, you must first press [F10] several times to create
enough blank lines for the new file. If your editor can't combine
files easily, you can use the DOS COPY command to combine the files:
COPY file1+file2 file3
This adds FILE1 and FILE2 together to make FILE3. Make sure there are
no spaces around the plus sign.
After combining the snap files, add text explaining how to use the
forms, reports, and menus. Then print the new manual.
Making a Tutorial
"""""""""""""""""
You can use the same file (the one containing all the combined
snapshots) to make a tutorial by using it with a program that shows
one screen at a time. There are some powerful, complicated, commercial
packages that will do this, but there are also some simple,
inexpensive ones. There's even one (DISPLAY.EXE) that's free. It's in
the public domain, written by P.J. Ponzo, Department of Applied Math,
University of Waterloo, Ontario N2L 3G1, Canada.
After adding a dozen or so simple dot commands to an ASCII file, you
can use DISPLAY.EXE to make your ASCII file into a self-running demo
with questions and pauses where desired.
Don't confuse the DISPLAY.EXE program with the R:BASE DISPLAY command.
They are totally separate. The DISPLAY command is part of the
RBASE.EXE file, so it works in R:BASE. To run DISPLAY.EXE, you need to
enter DISPLAY at a DOS prompt.
DISPLAY.EXE is available from many user groups. It comes with EXPLAIN,
a documentation file. Enter DISPLAY EXPLAIN at the DOS prompt to get
the explanation. both DISPLAY.EXE and EXPLAIN are included in the ZIP
file (MRIM1091.ZIP) that contains this October 1991 issue of Microrim
ONLINE. Remember DISPLAY.EXE is not a Microrim product, so Microrim
does not endorse, recommend, or support it. If you have questions,
call the author, P.J. Ponzo, not Microrim.
To run DISPLAY.EXE, you must have a file named ANSI.SYS. It comes with
your DOS operating system. After making sure the file is in your root
directory, add the following statement to the CONFIG.SYS file located
in your root directory:
DEVICE=ANSI.SYS
The ANSI.SYS file allows for colors and some simple graphics. I was
amazed by DISPLAY.EXE. It is small (24K), straight-forward, and the
easiest way possible to make a tutorial from snapshot files.
If you have R:BASE 3.1A or higher, you can use the new ZIP RETURN
command in R:BASE to zip out of R:BASE and run DISPLAY.EXE. This means
you can even include your tutorial as a menu choice. With tools like
these, anyone can make manuals and tutorials quickly and easily. In
the long run, good documentation will save you many more hours than it
takes to create.