This article spun out of the process of organizing the mess that had grown around my home computer system, but it had a delightfully unexpected result: shortly after publication, Prentice-Hall called and asked if I’d like to expand it into a book. Well, sure! I got to work on a more thorough discussion of the issues, whipped out a cover image using my laser and a piece of cheap pressed glass, and waited for the royalties to pour in. Much later, I learned that marketing is necessary… but it did get some nice reviews, one of which is over here in Online Today. There are also some images of my 1981 computer system.

Still, it was a worthwhile exercise, slowly getting my moniker out there in the computer book genre. As to making a fortune, well, I was adjusting my expectations.

by Steven K. Roberts
Kilobaud Microcomputing
January, 1981

Kilobaud January 1981 cover

Here’s an aid for disorganized or beginning computer users who find themselves drowning in paper.

It starts out innocently enough. You clear a space, install a computer and plug it in. You play with it a bit, juggle some I/O drivers, initialize a few disks, bring up an applications package or a language of choice and find yourself with a system.

You are on line.

You possess a powerful tool, a relentlessly educational toy and, if you’re not careful, a guaranteed ticket to insanity. Whether your reason for all the effort is business, software development, general utility, music or simply an obsession with computers, you have created a set of environmental requirements that cannot be ignored: from the tiniest microprocessor to the strange world of Amdahl and Cray, computers need organization.

More accurately, people need organization. Two years after implementing a convenient little I/O driver patch, you may change peripherals and need to unpatch it. At 300 revolutions per minute, a minifloppy rotates over 150 million times in a year of continuous operation — it needs replacement and the heads need cleaning. The wiring of a cable, the revision levels of the boards and the hardware patches may all become important when a problem develops.

Files get misplaced. I/O port assignments are forgotten. Data bases have no backups. What happened to the idea of “computer as appliance”? Unless your system is a sealed black box with a dedicated function, you may be in for some unwelcome surprises — unless, of course, you incorporate into your installation a few techniques of site management. The definition of the term “system” must be expanded to include your environment.

managing small system - 1

Levels of Organization

Outside the comfort of the card cage and the confines of an operating system, it’s a cruel and confusing world. The most elegant and beautifully integrated system architecture can be mired in poor documentation. Too often, the computer manufacturer or software vendor creates problems up front by ignoring this central fact, and a user saddled with such a system is, alas, usually powerless to do anything about it.

But assuming a quality system with reasonable documentation, you are in a position to implement a smooth-running, efficient installation. Attention to six major areas of system organization can make this possible, and make life happier for all concerned.

Hardware documentation — Oddly, this is frequently overlooked despite its almost automatic nature: manufacturers provide manuals, and hardware changes are seldom made without notes. Yet some “minor” details are easy to forget.

System documentation should start with a file cabinet or, at the very least, a dedicated file drawer. The hardware section should begin with records of purchases, warranties with the registration dates noted and the serial numbers of all equipment. In case of equipment failure or loss, this information can prove suddenly indispensable.

A second hardware file should be for factory support, with the names and phone numbers of knowledgeable people at the various manufacturers represented in the system. This is a good place for merchandise return forms, the names of a few local wizards and names of some other users of the same equipment.

managing small system - 2

Third, you should have accurate and up-to-date records of all changes and modifications made to the system: cable wiring, modifications to circuit boards and those temporary patches that somehow become permanent. Even such trivial items as a remote reset switch should be documented in the form of a sketch and filed.

A fourth file might be labeled, “Things to Do.” There is good reason to avoid frequent power cycles on a computer, and minor changes and additions, such as optional PC board modifications suggested by the manufacturer, can often wait until the next major shutdown. An organized queue of patches can help keep the system configuration up-to-date.

Fifth, you should have a file which documents the current system configuration. What boards are installed? How many spare edge connectors are there? Which memory board corresponds to which address range? What are the I/O port assignments?

This should also include a sketch of the overall system, showing all cables. You’ll appreciate a good configuration diagram when the system is moved to a new home.

And then, of course, you might have any number of hardware files detailing the various elements of the system. Kit plans, schematics, theory of operation and any other data relating to specific boards or peripherals should be sorted into convenient subheadings (16KZ memory board, Diablo Printer, Hazeltine 1500, homemade modem, etc.). Again, the easy availability of documentation about the system hardware can save time and frustration when it is time to repair, replace or modify the machine.

Maintenance — Immediately following the hardware section in the file cabinet, there should be a maintenance section. It should contain four files:

First, the system maintenance log. This is important! Every fix, every problem and solution should be noted for future reference. No matter how obvious the solution, it will probably be forgotten 18 months later when the same failure occurs again. A quick scan of the maintenance log might reveal the identical problem and prevent a lot of head- scratching.

Second, you should have a “Questions and Problems” list. Periodic conversations with the manufacturer yield more useful information if all of the accumulated questions are in front of you while you talk. It is too easy to forget half the things you wanted to ask.

Third, a preventive maintenance (PM) schedule is a must. Printers need to be oiled, filters and heads need to be cleaned, and analog portions of the system need periodic calibration. These things are normally forgotten in the complacency of smooth system operation, then regretted much later when failure results.

And last, the maintenance section should include the dates of acquisition of the system media — diskettes and cassettes in particular. This alone will not give an index of media use and optimal replacement time, but it will aid in keeping track of its age. Diskettes do fail from extended use — believe me.

Software documentation (environmental) — The environment in which application jobs run and in which development work is accomplished consists of an operating system, a monitor and various resources such as assembler, BASIC, COBOL, data base management system, text editor, text formatter and debugger. Also, you can have miscellaneous custom utilities, I/O drivers different from those provided with the system and macro libraries. All this code can be loosely lumped into the “environmental” category, and most of it is usually documented in the form of manuals. Keep the latest ones around, and put the others in the attic.

managing small system - 3

Patches to the operating system probably occur most often in the area of communication with I/O devices. A software driver for a daisy wheel printer or a memory-mapped CRT represents a key link between the system and the outside world — the documentation which defines it should not become buried in the inevitable computer room piles of paper, but should become file number one in the software section.

Like hardware, only changing more rapidly, software is identified by revision numbers. A complete record of these, along with any software registration forms, should be available at a glance. The first question asked by a software vendor when confronted by a request for help is usually, “What revision do you have?”

This file should also note, by diskette number, which revisions of the various pieces of environmental software exist on each piece of media. With 50 diskettes and six different revisions of the operating system, confusion can reign supreme (especially in situations where subsequent revisions are not compatible).

Again, you should have a file of questions and problems for the software supplier. If there is an obscure glitch in BASIC, it should be noted here so that the vendor can be informed and possibly provide a solution.

An important element in your environmental software file is a memory map. This is a drawing of the system’s address space showing the regions occupied by the operating system, user RAM space, stack area, ROM locations, the addresses of any memory-mapped I/O devices and so on. When you are adding a patch and looking for a buffer area that will not plague you in the future, this can be a big help.

Software documentation (applications) — The organization of information relating to applications software is very much a function of its volatility, whether you are its user or creator. If you are a user of an applications package, the principles outlined above apply, since it can be considered part of the system environment.

If the system is being used to generate new software, however, we have what could accurately be termed a can of worms. Revision numbers whiz by, sometimes up to the hundreds before the design is frozen and the program is delivered or put to work. This level of activity calls for careful management, both in the system and in the file cabinet.

There should be records, of course, defining the design criteria and the programming philosophies of which the software is comprised, filed by program or, in the case of small jobs (like “Miscellaneous Music Programs”), by category. Sample runs, memory utilization maps, debugging notes and latest listings should be filed together by job.

At the system level, you’ll want to reflect the revision number in the filename. Most systems provide the option of simply editing a source file by its existing name, producing a .BAK file as well as the new one, or creating a new name each time and using the old one as the input file. In the case of a complex project, the latter is preferable. In the case of text files and simple programs, the former is adequate. The difference lies in the amount of historical information that may be important in the evolution of the work.

In either case, you should have many backups, scattered across a minimum of three diskettes. The presence of multiple revisions on a single diskette is little comfort when an error message indicates a nonrecoverable media error in the directory — a rare, but crippling, event.

Operations — The area of system operations — the day-to-day running of the computer — is one in which some planning in the early stages of the system’s existence can pay off continuously throughout its operating life.

Operator conveniences work wonders. An ASCII code chart on the wall, reference cards near the console and a supplies drawer containing EPROMs, connectors, printer ribbons, typewheels, oil, head cleaning supplies, diskette labels, a forms ruler, razor knife and more felt pens than you’ll ever use will make life in computer room easy. The less you have to run around tracking down trivia, the better.

managing small system - 4

In the file cabinet, you should retain written procedures for the tasks that have not become second nature; e.g., patching the operating system with new I/O vectors, performing a CONFIG or loading certain debugging utilities. Strange but true, it is possible to forget some of the less frequently used procedures.

If the system has not yet been equipped with a multimegabyte hard disk, the problem of organizing dozens of diskettes must be faced. In the case of minifloppies (5 inch), the organization of an active system can create considerable confusion. This can be minimized by — you guessed it — careful planning.

First, the diskettes should be sequentially numbered (irrespective of their contents) and separated into broad categories. There may be disks for writing and storing BASIC programs, disks for creating text files and disks for data base. The point is to separate them   by function; this will eliminate the confusion that can result from having articles, I/O drivers, a COBOL accounting job and miscellaneous BASIC programs on the same diskette.

Second, any critical file should be copied onto one of a number of general backup diskettes, which are stored in a different location from those in daily use. A fire, the catastrophic introduction of a magnet into the room or a careless coffee spill can have dismaying effects if all of the system files are in the same box. If you are doing custom software and possess absolutely irreplaceable data, invest in a safe deposit box. It’s cheap insurance.

Third, you can keep track of all those files by periodically preparing a master directory of all of your diskettes and manually updating it as the files evolve. It would be pleasant to dedicate an additional drive to the system, along with appropriate support software, to automatically update a master directory file each time the directory of another disk is changed. This, along with some dedicated data base techniques, would effectively solve the problem of organizing a system environment consisting of large numbers of floppies.

Lacking that convenience, however, generating a complete directory manually at appropriate intervals considerably simplifies the task of  finding a long-dormant file.

And fourth, each diskette should carry a brief text file for identification. A convenient way to name this file is IDENT.MYY, where M is a month code (0-9, A and B) and YY is the year of the most recent change in the IDENT file. Thee file consists of the diskette number, its acquisition date and a brief summary of its use and present function, including any error incidents. This, printed with its directory upon each generation of the master directory file, fills the missing links in the system files’ documentation.

Attention to  these and similar aspects of system operation can make computer use much more pleasant than it is when confusion reigns. Organizational techniques add little to the operating overhead, but pay off handsomely in convenience.

The computer room library — There are sources of pertinent information that need not be integrated with the active system files, disk and otherwise, that we have discussed so far. These are vendor literature, magazines and books. There are thousands of published programs which together represent a powerful resource to the microprocessor user, along with hardware articles and philosophical comments. How can you possibly use this massive resource effectively?

The fundamental solution is a computer room library, cross-referenced as heavily as your time permits. The problem, of course, is that the sheer volume of information can make this cross-referencing a prohibitive task. Even with the use of a data base management system, time required to update may be too expensive to consider.

An intermediate solution is the creation of another category in the system file cabinet. Use it to save annual indexes from the magazines, notes about articles of particular interest and photocopies or clippings of immediate interest. Published information can be a real time-saver, and it is worth trying to organize it.

Conclusions — If you find yourself plagued by relentless stacks of papers that are too valuable to toss out but too numerous to try to organize, take the time to create a file drawer. Starting with the categories outlined in this article, add files that fit the requirements of your own unique installation and of your work. When you have a definite place to file almost any piece of information, those piles take a lot longer to form.

Until we have self-documenting systems, large cheap disks that back themselves up and hardware and software so perfect that documentation is superfluous beyond the “how to use it” level, we will have problems in organizing the small system environment. These requirements are an established part of the data processing industry, but only with the recent proliferation of microprocessors have they arrived in such force at the doorstep of the small businessman and hobbyist.

But as long as the potential user is equipped with the organizational techniques to deal with this flood of information, the threat posed by computers to his or her sanity can be held at bay.

The back cover of the book that fell out of this article for Kilobaud