ticalc.org
Basics Archives Community Services Programming
Hardware Help About Search Your Account
   Home :: Community :: Articles :: Documentation Lacking
Documentation Lacking

Posted on 11 October 1997

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.

  Reply to this item

Re: Documentation Lacking
thiemster Account Info

A good idea for organizing calculator files is to make folders with each program. Then, you just have to know that name of the folder, open the folder, and all of the stuff that you need is right there.

Reply to this comment    18 March 2006, 23:12 GMT

Re: Documentation Lacking
Sean XDIR Account Info

I totally agree, it can be very frustrating if theres no/not sufficiunt readme files. about the readme names: I will use my own (just submitted) prog as example. prog name: XYWars . Readme name: XYWarsreadme. Ofcourse you can change a readme name but I think that the author should make all it work.

Reply to this comment    21 August 2006, 15:07 GMT

Re: Documentation Lacking
calcproductions  Account Info
(Web Page)

Well this topic hasn't been touched in years, however I have noticed the terrible lack of a decent documentation. Thus I am currently making a easy-to-use program where the programmer just inputs the key information for his game and my program outputs a .txt with all of it organized and set up.

See the URL of this post for screenshots.

It won't be out for a while, but it can change all this if people use it.

Reply to this comment    10 October 2008, 04:59 GMT

Re: Article: "Documentation Lacking"
Anonymous

I also agree that documentation is crucial to the overall enjoyment of any program, be it a shell, game, or anything else. I try to include multiple text files with my games(which I haven't yet uploaded)like these: a readme.txt file for people who just want to see what the game is about, a manual.txt file with more in-depth directions(only for more complex games), and any other texts like previews of future versions of the game. I think that if programmers took more time to document their games(like Bill Nagel's Super Mario 86), people could enjoy them more.

Reply to this comment    10 October 1998, 07:05 GMT

Re: Article: "Documentation Lacking"
Graham

Great comments.

Reply to this comment    22 October 1998, 15:52 GMT

Re: Article: "Documentation Lacking"
AGENT-TI
(Web Page)

Filename != Readme.txt

(in the file:)

The full name of the program:(No funny graphics made from text and a whole bunch of spaces)
Version number (included in the name above?)
Author1:
e-mail:
web-site:
Phone-Number:

Author2:
etc:

The program to run (in case of several sub-progams)
genre:BoardGAME/Arcade/Simulator/
Size of programs:
1. Prog1; 2342 bytes
2. Prog2; 56 bytes
...
x. Progx; x bytes
Total Bytes=9453 bytes =93% of ram
Additional ram required to run this program

Description of the program:

Remember that game that did so,and so? Well this is it and it works twice as well
(This is bad commenting)
You controll a ball through a maze
Don't run into any of the following:
1
2
3
4

Keys:
(if they use THE standard keys/In debate now)

STANDARD+
[x]=Attack
[y]=Run
[GRAPH]=Map
[v]=restart the level

you can only use [y] while in battle (etc.)
If you fall off press [v] to restart the level
comments about other buttons here...

Version History

1.0 Original version
2.0 Fixed crash when loading
3.0 Beta 24.5622? (there should be a standard for this.)

---End of file---

Anyone want to add something?

Reply to this comment    12 November 1998, 22:08 GMT

Re: Re: Article: "Documentation Lacking"
Chris Fazio  Account Info

i think u explained that better than i could've

Reply to this comment    13 January 2000, 00:49 GMT


Re: Re: Article: "Documentation Lacking"
angus  Account Info

I disagree about no funny graphics made from text and spaces.

Reply to this comment    8 December 2003, 03:59 GMT

Re: Article: "Documentation Lacking"
Joshua Rothenberg

Is anyone here familiar how GNU(http://www.gnu.org) handles software documentation? There should be a Documentation section on this site where anyone can write documentation for programs and games that lack it. This is one possible solution to the lack of documenation.

Reply to this comment    7 August 1998, 21:26 GMT

Re: Documentation Lacking
Keith Myers  Account Info

I agree! I own a T-I 83 plus SE and there is almost no doccumentation for programs

Reply to this comment    21 December 2002, 21:47 GMT

Re: Article: "Documentation Lacking"
Master Nick
(Web Page)

I completely agree that there is a need for more documentation. I am a software developer myself and I think that including documentation with my programs is esential. I find it very beneficial to myself and the user as well as other developers. Documentation is a good place to let people know who put all that hard work into writing a program. It tells the user how to use your programs without having to mess around with it all day. Documentation in my programs is also useful to other developers. I frequently recieve email from people who are trying to get permission to make add ons for my programs. As for that list of items to include in documentation, I feel it should go beyond that. I think technical information should also be included, for another developers use, especially for word processors and similar programs. It will help other developers more easily write add ons for your programs and thus further promoting your programs to user.

Reply to this comment    19 August 1998, 01:35 GMT

  Copyright © 1996-2010, the ticalc.org project. All rights reserved. | Contact Us | Disclaimer