The following text was written by Achton Nick
Netherclift:
For about a month now, I've been the content owner of a TI-83
calculator. Almost since day one, I've searched the Internet for games, utilities, pictures
and everything else one could want when working on a TI in school. Thus, ticalc.org and
other large sites have been my preferred homesteads when downloading updates, beta's, texts,
pc-programs and the like. When you have an enormous amount of small files, you need to have
some good organization on your harddrive, or everything becomes mixed up.
I was
very soon annoyed with the quality (and quantity) of the documentation for the games and
programs. Apparently, the programmers have been writing readme's for so long, they no longer
care if the user has to spend half an hour trying to figure out the plot or usage of the
program in hand, or they just don't know how to write anything but assembler code anymore.
In any case, the text-files are inadequate, and this is the main inspiration for writing
this article.
It is important for the users of the software to have a complete and
standard amount of documentation for each program. Otherwise, the user spends needless time
trying to figure out the program. Unfortunately, this is not the only problem. In some
cases, the ZIP-files are completely without readme's, which is totally unacceptable. This is
a big "turn-off" for someone just looking around for useful games or utils. But often, when
documentation is included, it is named README.TXT. This is almost just as unacceptable. When
I've downloaded updates and the likes from the Internet, I leave them all in the same
directory and then unzip the group files along with their respective text files at the same
time. If half of them are named README.TXT, this causes a problem. Therefore, I first submit
that the programmers attempt to name their text-files after the name of the group or program
file. This makes it much easier to maintain a logical directory and file structure on one's
harddrive.
Second, to get back to the content of the .txt-files, I think that there
ought to be included certain information within them. Mainly at the top of the file, so that
the reader can quickly obtain a good, clear idea of what the program in hand is to be used
for. The following things should be included in the header:
- Name of
program/game and group file (if applicable)
- Name of single program files or similar
(.83i, .83l, etc., if applicable)
- Author's name and email address
- Version no. (if
applicable)
- TI-calc to be used and GUI (if applicable)
- Programming language (BASIC
or ASM)
- Size of group file in memory
- Amount of mem needed to run (if applicable)
- Release date and site (WWW-link)
- WWW-link to future updates (if applicable)
- Short description of the program
- Copyright information
After this, there
ought to be installation notes, the program documentation itself, revision history, etc. The
important part is the list above.
I know that you can't just waltz in and tell
everyone to release their product in this and this manner. I apologize if I've offended
anybody with this article. It's just been bugging for a long time, and I felt that this was
the right time and place to issue some complaints.
Not that there is much to
complain about the programs themselves. The games and programs themselves are top notch. No.
1's - every one of them. My deepest respect goes to Bill Nagel, Ahmed El-Helw, Andy S. and
everyone else that work hard and efficiently on useful stuff, we can spend our boring
danish-lessons on. Hats off. However, the documentation is just as important, and frankly it
currently sucks.
