Portal:AOL-Files/Articles/Procedures for Writing File Descriptions

Following are guidelines and procedures writing file descriptions. This is a draft, and may change based on feedback. Send comments to both PCProducer and PC LibMgr. It is most important that a version number or date is given for the file.

1. BASIC DESCRIPTION STRUCTURE (Print out and use this as a template) ======================================================
File description template. "|" shows were text starts. Text in bracket should be replaced with appropriate information.

SUBJECT: |[FILENAME: Vn.n Descriptive Text - 32 characters max]
AUTHOR: |[Author (Company)] [If unknown, put "Unknown"]
EQUIPMENT: |[Optional]
NEEDS: |An UnZIPing Program [and special software, other files]

This file is Self-Extracting - requires nnn,nnn bytes [when applicable]

Keywords: |[Author, Company, other descriptive, special keywords]
Type: |[Shareware, Public Domain, Freely Distributed, Demo]

Version: |[Give file date - Use only if no version number available | or if version number is too long to fit in subject line]

[Note: Special information - optional - see instructions below]

[Descriptive text - no hard carriage returns]

Note: [Optional - see instructions below]

To run, enter: [FILENAME (Options)]

Documentation: [FILENAME.DOC]

Downloads for previous version: [Get total from previous description]
=====================================================================

2. EXPLANATION OF BASIC DESCRIPTION STRUCTURE

The above file description template illustrates the capitalization of words, alignment of text, and spaces between lines. Examples given below are for files in the WordPerfect Support Library. Look there for more examples.

DO NOT PUT ANY REFERENCE TO THE ONLINE SERVICE OR THE UPLOADER NAME IN THE FILE DESCRIPTION OTHER THAN UPLOADED BY (UPLOADER NAME) if you reZIP the file. Do NOT include @America Online, @PC-Link, or @Promenade, etc. If the uploader/author wishes comments on his program, request he place the online service name and ID in the documentation that he provides with his program. No reference to this should be included in the file description.

SUBJECT: - Align text in headings by adding three spaces after the colon in SUBJECT:. The subject line should start out with a generic filename in all caps without the version number attached. Then put the version number. This is to provide a searchable filename that the member can use. Taking an example of the file NYWRD22A.ARC, the subject line should be "NYWORD: V2.2 New York Word (Part 1/2)." If more space is needed, eliminate "Part" in the above title. In this example, the generic filename is what people would most associate with the word processor, New York Word. See special section, WHAT IS A GENERIC FILENAME?

To save space in the subject line, a slash (/) should be used instead of the word "or" when appropriate. The ampersand (&) should be used instead of the word "and." You can use abbreviations in the subject line if you include the unabbreviated word as a keyword.

There will be exceptions where the filename shouldn't be given; like when filename is too generic, i.e., when the filename does not refer to the subject material in the archive. As an example, the file WP50.ZIP contains WordPerfect Clip Art. The uploader named the file without any regard for subject matter in the archive. The subject should be "CLIPART: WP 5.0 Clip Art," where WP 5.0 refers to WordPerfect 5.0 rather than the filename. Two other exceptions to starting with the filename are in the Graphics Forum and Music Forum. Graphic filenames aren't appropriate for this space in the title. The type of file, GIF:, PCX:, MAC:, is better. The Music Forum has approved exceptions also. Generic filenames can also be the name of the executable file.

AUTHOR: - Give author's full name. If a company name is available, follow with the name with it in parenthesis. If only a company name is available, you don't need the parenthesis. If neither an author or company name is available in the file archive, use "Unknown." Don't put "Unknown" just because you are too lazy to search for it in the documentation. If the author's name and/or company is in the documentation or displayed when running the program, it MUST be given.

EQUIPMENT: - Use this line ONLY if special hardware equipment is required. Give the hardware required (such as Tandy Graphics or Tandy Sound, VGA), memory if beyond 512K, graphic adapter needed, mouse, etc. If equipment is optional, put "(Optional)." If no special equipment is required, delete this line. Do not use the word "EQUIPMENT:" with nothing after it. DO NOT PUT "MS-DOS Computer" in the equipment specification.

NEEDS: - Use the following standard text to specify .ZIP, .ARC, or self-unarchiving files:

An UnZIPing Program <=== Note capitalization and single "P" An UnARChiving Program

Follow this with special programs required such as "and Part 2" or "and WordPerfect 5.0" or "Tandy BASIC", MS-DOS/PC-DOS 4.0, etc.

This file is Self-Extracting - requires nnn,nnn bytes

See template above for position of Self-Extracting note when applicable.

Category: - This was used in older file descriptions but is no longer used. If you edit an older description, take it out.

Keywords: - Note capitalization for titles below this point. Also, there is one free line between "NEEDS:" and "Keywords:." (Self- Extracting note is an exception. See Template.) Start with last name of author, then company name. Don't include generic words of company name. For example, with "OCR Software Corporation" you would just use "OCR" as the company name. DO NOT REPEAT words from the category or subject line as keywords. All keywords and words in the subject line are included in the search. Limit keywords to one line.

Special keywords follow the other keywords. Examples are:

Win3 - for files requiring Windows 3.x
Win2 - for files requiring Windows 2.x (Win2, Win3 when file can be used with both.
PCVALUE - Programs that are a special value due to a low shareware fee, public domain programs of exceptional quality, etc. Use all CAPS.
Top Pick - Self Explanatory
PD - Public Domain
FD - Freely Distributed. Use this when stated as Public Domain but has a copyright. Also for files supporting commercial programs when distributed by the commercial company and allowed to be distributed. (Such as WordPerfect Support files from the WordPerfect Corporation or support files from Microsoft.)

Category: - Not used anymore. This field should not be included. There is no need to edit older files to delete this field, but if you are editing the file description anyway, delete it.

Type: - This tells the distribution status of the file. Do not give the shareware cost if it is shareware. Typical entries are

Shareware
Public Domain
Public Domain - Registration requested
Freely Distributed
Demo
Shareware - Working Demo

"Freely Distributed" is similar to Public Domain except that the author shows a copyright on the program. The term Freeware should NEVER be used. It really means Shareware though some think it means Public Domain. Don't use it even if stated in the documentation. Use Freely Distributed instead.

Demo files should be moved to the Demo library and you should notify PC LibMgr. But Shareware - Working Demos should remain in the applicable libraries. Demo files are usually commercial programs from Microsoft, WordPerfect Corporation, etc. that are not fully functional.

"Shareware - Working Demos" are usually shareware programs that have abbreviated functions or limited output from the registered versions. Use your discretion with this term and weigh it against the term, "Shareware." Only use "Shareware - Working Demo" if it is a full or partially functional program. As a rule of thumb, most programs that require a registration fee for an enhanced version will be either "Shareware" or "Shareware - Working Demo." Explain in the description of the program just what does not function if the program is crippled in any way.

Version - Use this line only if no version number is available for the Subject line. Use the latest date of the executable program file. Make sure it is not the date of a configuration file from the previous user of the program. The exception to using this date is if it is dated 01-01-80. Also, do not use the date you downloaded the file. If you cannot determine a date, delete this line. When a file is not ZIPed when uploaded, and no version number or date is given in the file, just leave it blank as there is no reliable version or date available. This occurs mostly in Music or Graphic files.

Special information - This is where special information will be given. If the file had to be re-uploaded, put "(Uploaded by ....)" here (without "Note:"). If you know the difference is slight between a previous version of the same program, you want to add a statement here like "This version corrects a bug when used with Trident VGA adapters."If you have the previous version and do not have this graphics adapter, you do not need to download this version." Another example is "Part 2 of this program, which contains documentation has not changed. You do not need to download this file if you have the previous version of the program." Avoid statements like "This is the latest version....." or anything that will lose significance over time. Also add something if the only change is from an ARC file to a ZIP file. Any uploaded ZIP files should be used to replace the same ARC version.

Description - Do not re-invent the wheel. If possible, always copy text from the program documentation that describes the program. You can usually find this in the introduction of the program. Avoid statements from the author that promotes his product by words such as excellent, best, exceptional, etc.. If you believe a product is excellent, state that in the Notes: section. Do not include odd formatting of the text even if the documentation has it. Avoid things like "...." or "---" or anything that makes the description look choppy. Keep the description short unless you have to convey special information.

When a file description from a previous version of the program that is on-line is written well, you can use it instead of the above unless there are significant changes. Only do this if it is a good description, though.

There should be no carriage returns in the text except at the end of a paragraph. At the end of a paragraph, there should be two carriage returns. If your text processor automatically puts in carriage returns, and you import the file description into the edit area online, remove the unnecessary carriage returns. If items are enumerated, do not indent them. All text should be flush left. See example below. The reason for not putting carriage returns is that the width of the text window may not always be constant. The total number of lines of text supported for the entire file description including header information is 50 lines of 68 characters max. Do not exceed that.

If a program has more than one part, do not repeat the description in the other parts. Use the statement, "For a complete description of this program, see Part 1." Also state which part contains the documentation files.

Note: - Do not put your name in the Note: area. Do not use "Notes from PC ....:" but you can use "Notes from Uploader:" when there are special comments from the uploader. If you think a program is excellent, state it here. If you think the program has difficulties with certain equipment, state that here. If you think the program is worthless or has too many bugs, make a recommendation to PC LibMgr that it not be made available and give the reasons. Don't go overboard with Notes. If you have Note: at the bottom of your text, you may not want to use the term, "Note:," for special information that is given at the beginning.

Following the notes, explain how to run the program, and give the name of the document file. Use the following format:

To run, enter: FILENAME (Options)

Documentation: FILENAME.DOC

Only include options for running the program if they are absolutely necessary or when the user should be especially aware that they are available. If the program is self-documenting, use something like "Program is self-documenting, press F1 for help." If control codes or alt-keys are used to get help, use the format, CTRL-n or ALT-n. State the format of the documentation if it is other than ASCII.

If ESC or press "q" does not exit the program, specify how the program can be terminated, i.e., if it is not obvious.

Downloads for previous version(s): - Here you would put the number of downloads shown in the previous file description. If you don't have a number to put here, don't include the line.

3. SAMPLE FILE DESCRIPTION

SUBJECT: MACTUTOR: WP 5.0 Tutor on Macros
AUTHOR: Gordon McComb
NEEDS: An UnARChiving Program and WordPerfect 5.0

Keywords: McComb, Tutorial, Template, WordPerfect, Word Perfect
Type: Public Domain

Version: 06/01/88

The text files included are from a series of columns written by Gordon McComb on WordPerfect 5.0 macros. These appeared in issues of Computer Buyers Guide and Handbook (used by permission). Included is:

1. An introduction to the WordPerfect 5.0 macro feature,

2. An explanation of macro editing and discussion of some advanced macro programming statements, and

3. Samples of four programmed macros; a quiz macro, two example telephone message macros, and a question and answer sheet used interactively with the quiz macro.

Notes from Uploader: A very good tutor for Word Perfect 5.0. The macro language in WordPerfect is great, but complicated. This is the best tutor I have seen on the subject, really smooths out the learning curve.

To use the tutorial, start by reading the README.DOC file with WordPerfect.

Files in the tutorial are MACRO1.DOC, MACRO2.DOC, MACRO3.DOC. They are WordPerfect formatted files.

4. WHAT IS A GENERIC FILENAME?

A Generic Filename is a word of up to 8 characters that can be used to describe a file. Since we have a search utility and keywords (search words) that can be used to quickly find files, we want the members to associate a file and all updates to it with a filename that is independent of version number. This can be the name of the program (without version number) or the name of the executable file, or whatever makes sense. For example, in the Music Forum, all music files that use the Sound Blaster music card have BLASTER as the generic filename.

As another example, the PC-Write word Processor should always have PCW as the generic filename and PCWrite as a keyword (PC-Write in the subject line). The files may be PCW303A.ZIP, PCW303B.ZIP or PCW303C.ZIP, but always the member can find it using the search word, PCW or PCWRITE. Likewise, when the version number changes to version 3.04, the generic filename of PCW and keyword of PCWRITE is still good for searching for the file. Using the search utility, the member will come up with all listings using PCW or PCWrite including supporting files, such as Writer's Heaven. Note in this example that similar variations on the words used in the subject line should be added to the keywords list.

This promotes downloading, assures that the members sees the latest version of the file, even if we have forgotten to remove a previous version, and also helps us find previous versions to delete when a new file becomes available.