A sysop's 13 biggest gripes with file_id.diz descriptions
The most common mistakes 

file_id.diz is not just another file name. It is the name searched for by other
software (including BBS platforms) to place the file description in a file
base. 

To coordinate with the other software a file_id.diz must follow the specific
format it was designed for: line length 45, no blank lines, not more than a
handful of lines. That form allows BBS software, upload checking software, and
archive shells to extract the information in the diz and place it in a
searchable list of file descriptions. 

You can download our program to create them, DIZGEN10.ZIP. 

A ZIP or self-extracting EXE archive file_id.diz should be a small ASCII file
giving: 

1. the program name 
2. the version of the release 
3. the operating system(s) it runs on 
4. what the program does 
5. anything unusual about it, and 
6. what other programs are needed to run it. 
With Shareware, it's nice to find the price and S&H there. If it's an award
winner, the phrase "Award winner." 

File description lists vary in the number of lines allowed per file. Most BBS
software defaulted to 8 lines, and that became a de facto file_id.diz standard
length. 8 lines. Sysops could change the number of lines allowed per file
description and many did, either raising it (the FHOF allows 40) or lowering
it. If the file has too many lines the extra will be hacked off in mid-thought.


A large number of software writers screw up the diz because they haven't a clue
there's a form to follow. We've actually seen 100-page doc files named
file_id.diz. And we've seen worse than that. 

Among scores of wrong things in a diz, this is our choice for the 13 most
frequently committed errors. We are posting them as a guide to what not to do. 

The diz fails to say what operating system the program runs on. A common
failing of OS/2 programmers which is why we quit distributing OS/2 software.
These guys are too focused. Some don't even mention in the docs that it's OS/2.


It's a BBS utility but gives zero indication what BBS platform it runs on.
Again, even some docs fail to say. 

ASCII/ANSI art in the diz. The sysop must choose between stripping it out or
taking the easy way and tossing the package in the bit bucket. FHOF strips it
out. Look at the file descriptions on PCB's SaltAir support Board to see what a
mess a file directory becomes when the art isn't stripped out. Few sysops
tolerate that. 

The author's address is in the diz, or instructions how to register the
program. Utterly wrong place for these, and they steal what little space is
available for the program description. While it's good information, it's of no
use until someone downloads the program, tries it, and wants it. At that point
he's going to look in the docs or a REGISTER.ME file for that info. Have you
ever used a diz file to find an author's address? Neither has anyone else. 

It's formatted wrong. The lines are more than 45 characters, or a great deal
less, or blank lines are included, or it goes on for dozens of lines beyond any
reasonable space provided by a BBS. 

It's all adjectives and hype with little program description. 

It names every award the program won, leaving no space for why it won or what
it does. Awards are good information but belong in the docs. The phrase "Award
winner" is enough for a diz. 

It has words spelled wrong. An author who doesn't spell check his most public
file reveals how thorough he is. In our experience, a diz with 2 or more words
spelled wrong always means a buggy program. 

The diz is written for other programmers instead of for the end user. An
overly-focused programmer tells how he did something rather than what he did.
90% of the readers get nothing from that. Such information belongs in the docs.


Exclamation points are used. That's a reliable guide to the author and you can
take this to the bank. No exclamation points commonly means a mature outlook. 1
used and he's following convention. 2 to 4 and he's impressed with himself. 5
or more and he's immature no matter his age. The FreeHOF tracks these things.
The average is 3. The record is 37, held by RSMON150, Resource Monitor. We
remove all exclamation points when editing file descriptions. 

Capitalizing The First Letter Of Each Word In The Diz. Hard to read, often
creates gibberish like Dos instead of DOS. An example of mindless form over
function raising the possibility the software also embraces form over function,
which sucks. Alas, a sysop's poor choice of software to create his file
descriptions can force that, making the author look bad. 

No capital letters at all. Programmer fancies a different drummer. Can mean a
better program but usually doesn't. 

The diz fails to say what additional programs this one requires, like DLLs, or
even to say "see docs for DLLs needed." That information used to
be elementary
for an author who gave any thought at all to the end user. 

Last and least are the common syntax and grammar mistakes. Here are a few: 

Extraneous words which clutter a description while adding nothing. Examples: 
- the word "different" as in "10 different ways" or
"10 different languages."
10 ways or 10 languages says the same thing. 

- the word "that" is unneeded 90% of the time it's used. 

- the "and every" in the phrase "each and every." 

- long phrases to do the work better done by one or two words. "It has the
ability to make a connection with" we delete and replace with
"Connects with." 

- putting a file's date in the diz more than once. (Again that's often the
fault of sysop software.) 


Other needless repetitions, such as "sorts the files, sorts the directories,
sorts the index." We replace such a line with "Sorts DIRS, files
& index." 

The use of obscure acronyms known only by the initiated which are never
explained. Sometimes the docs don't explain them. 

The name of the program repeated 3, 4, or more times in the description. It's
only needed once. The single most frequent change we make is to replace a
phrase like, "Picture Mania can usually convert ..." to the single word
"Converts ..." 

Extra credit: putting the Shareware price and S&H in the diz. Some authors do
this. Usually the sign of a good program as it shows the author has confidence
and doesn't feel a need to hide his price. And take this to the bank: what's a
sure sign the author knows his price is unreasonable? Answer: he uses the word
"only" before the price. "Only $10" or "only
$29.50" is rare. "Only" begins to
creep in as the price approaches $100. Above $100 and you can bet on it that
"only" will precede the price. "Only $249.90 + $9.90
S&H." Check some file
descriptions and prove it for yourself. 



This Bulletin was written by Rey Barry and is placed in the Public Domain. It
may be freely copied and used. 
-----
The Parallel BBS * Ontario, California * 
--- SBBSecho 2.00-Win32