The Freeware Hall Of Fame
Presents:

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's the special name searched for by other software (including BBS platforms) to find a file description which it can copy into a BBS file base.

To coordinate with this 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 - and only that - allows BBS software like PC-Board, upload checking utilities, and archive shells to extract the information in the DIZ and place it in a searchable list.

You can download our program to create a proper file_id, DIZGEN10.ZIP. After you create it, the file goes inside the archive package you are distributing.

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 on Bulletin Boards and the Internet 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 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, here's 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 he's not thorough. 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 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 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 popular (and stupid) program used by many sysops re-wrote the DIZ to do that, making authors look bad.

  • No capital letters at all. Programmer fancies a different drummer. Can mean a better program but seldom does.

  • 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 authors 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 serves no purpose.

    • long phrases to do the work of 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 can be the fault of poor software chosen by the sysop.)

    • 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.

      It's not only shareware writers who do this; it's a national characteristic of American selling. We see it all the time in newspaper stuffers from places like Sears. Perhaps it's subconscious honesty, this need to flag absurdly high prices with only.

    ********************

This Bulletin was written by Rey Barry and is placed in the Public Domain. It may be freely copied and used.

To return to the FreeHOF Home Page click here

The name Freeware Hall of Fame is Service Marked by Rey Barry (rey at cstone.net)
All rights reserved
Page last touched June 5, 2019
RBA Logo