Surviving Systems We Work With 0. A DOCUMENTER'S NIGHTMARES: _____________________________ Be brief. Be conversational in online help. Discard useless information. Emphasize the important information. Say, this is important, or this is the most common usage. 1. THE INFAMOUS MAN COMMAND ___________________________ All UNIX users learn that this is where information is. If you don't put something here, you've lost your best chance to help them. Besides that, it's a good idea to document every piece of software you put out, just as though it were a system command. Users don't make fine distinctions. If your first page is not helpful, the user won't read the second. It had better be clear, and easy to read. Start with a single line or short sentence, separated from the rest of the text by a blank line. The user will appreciate being able to tell instantly whether or not the right information has been found. Users assume MAN information will be unhelpfully terse and yet boringly extensive. You can surprise users by making a short MAN page that is conversational. Put the heavy duty documentation somewhere else. Users can figure out how to use MORE or GREP or an editor to locate information in a document if they find out they really want it. Ignore the standard MAN page formatting. TROFF is too hard to use, and the results are unimpressive. The logical structure (NAME, SYNTAX, DESCRIPTION, and so on) is unreadable and tedious. Use a sensible format for your environment, and use it all the time. That way, users will know what they can expect from your man pages. Things I haven't done: I have no interest in using TROFF. I don't even find underlining and boldface worth my time. Even TAB's are a luxury I don't want, since I can't guarantee consistent display of information on all terminals. I have not tried to use the keywording feature of MAN. This would allow users to type "man -k chemistry" and get a list of MAN topics whose definition line includes the word "chemistry". I haven't figured out what to do when there's a conflict; the system MAN command and I both want to supply information on a topic. ULTRIX seems to ignore my stuff. UNICOS displays them both, with mine second. 2. ONLINE DOCUMENTS ____________________ The MAN page is the wrong place for detail. That goes in a document. The difference between a MAN page and a document is: I don't know where MAN pages are, I can only ask to see them. I don't expect to read more than two sentences in a row. I know where documents are, and I can do anything I want to them. I expect to find at least a paragraph or two that I will want to read very carefully. I may need to skip around looking for key words. Some of our documents are simply a copy of the MAN page. Others are couple of pages of instructions. Others are catalogs of all the subroutines in a library, and how to use each one. Others are copies of various hardware and software manuals. 3. USE PLAIN TEXT FOR ONLINE DOCUMENTS _______________________________________ I am a plain text fundamentalist. I am convinced that the plain text online document provides the most information at the least cost. It is rapidly produced, easily displayed and ported to a variety of machines. It can be searched and edited and mailed and extracts can be used as needed. I don't hate formatting: I'm glad if someone else does it for me. I'm surprised if it works for me. Italics, formulas, and bold face can be very helpful. But I don't think it's cost effective to do presentation quality documentation online. Formatting a document means that You can't run a spell checker on it; You never have to hit RETURN (on a Macintosh, anyway); It's no longer text, it's data, so you must debug it! The display of the document on any other device depends on how the user sets that device, what fonts are available, whether the user has the correct version of the display program, whether binary information is involved. The user can't search nor edit the document. The document becomes a programming project, broken up into modules and include files and graphic images. It's not enough to be a good writer and typist. Now we want programming ability too. This overburdens some staff, keeps other staff from producing documents, and writes off the talents of many technical writers. Even "minimal" formatting destroys the ability to use documents properly. TAB's display differently, or show up as CONTROL-I. Underscore-Backspace characters, if not interpreted properly, make the document unreadable, and can generate "line too long" errors in file transfer or editors. Simply justifying lines by adding spaces means that a search for "Linear Algebra" will fail even more often than before. Your FORM-FEED character that breaks your pages every 66 lines is worse than useless when I print your document on my 60 line pages. Are we in the publishing business? Compare the usefulness of a plain text file and a PostScript file. When a user prints a PostScript file, the user has already decided that the file contains useful information. The user has probably found the desired information, and now wants to see it in a pretty and readable format. But that's the only use for a PostScript file, to be transferred and printed. An online document can be used in many ways. 4. NEWS SYSTEMS _________________________ All systems need a place to announce news. The login message or message of the day must be kept short and current. Otherwise, users ignore it. News systems differ in how they announce that there's new information. Our users ignore the UNICOS news, and I can understand why. VMS BULLETIN can be a little pushy. RN is too discrete. I encourage our bulletin posters to specify an expiration date of one month on their posts. However, we have announcements such as "The Seminar on 14 February 1992 is cancelled" which are scheduled to expire on 8 November 1994! Another reason to do this is that we frequently post a series of messages like: Cray will be going down, Cray is down longer than we thought, Cray is back up. If we don't delete these silly things, than someone logging in a day later has to wade through this stuff to find important news. Bulletins and news messages can be up to a page, but after that, users ignore them. I encourage posters to store details in an online document, and mention that in the post. 5. NEWSLETTER ______________ We keep copies of our newsletter online, on ULTRIX, UNICOS and VMS. Why? After all, they've got a copy somewhere. I find that people have a very good recollection of the topics of articles, without remembering the details. People throw away the newsletter, and then realize that they need information from it. The online articles are plain text files, and we tell the user where they are. There is a newsletter directory, with separate subdirectories for each issue. However, most users prefer to run a simple interactive program that we provide, which tries to do the obvious things: Display an article, a page at a time, List the issues, and the titles of articles, Search for a keyword or phrase in all articles, Copy an article to a file. with the least amount of user work and thought: RETURN will gradually page you through all the articles, you are constantly reminded that "H" will print out help, other commands are one letter (Q for quit, S for search). I think the user interface for this program is pretty good. But I've been concerned with the maintenance costs. First of all, you could probably write a shell script to do everything I did in FORTRAN, if you only wanted to run on one machine type. A shell script would have been easier to "spin off" to some other staff member. FORTRAN is not a popular choice for this kind of task. Secondly, and in part because I did not write a shell script, the program has to be told what the subdirectories of the main newsletter directory are. This information is stored in a file, along with the number of articles and their titles. This means the newsletter program requires two files to run properly, the program and the information file. And it means that every time I put out a newsletter, I have to enter into the file the name of the subdirectory, the number of articles, and their titles and file names. 6. DOCVIEW, IMSLDOC, NAGHELP, SLATECDOC ________________________________________ DOCVIEW - ??? IMSLDOC - A consistent interface. NAGHELP - Makes no sense without a VMS HELP background. Even then... SLATECDOC - ??? 7. SUPERNET NEWSLETTER READING PROGRAM ______________________________________ In March, I was informed that there was a new online service, sponsored by Supercomputing Review. This service, known as SUPERNET, makes available job postings, bulletin boards, software offerings, and other items of interest to supercomputer users. Of particular interest to me was the availability of newsletters from the various centers. I sent a copy of our January/February newsletter to SUPERNET, which was placed online. As installed, you have to select NEWSLETTERS from the main menu, then choose the center whose newsletter you want to read, and then the issue. At that point, you see the list of article titles, and you can choose one. When I sent the March newsletter, I was unhappy to discover that SUPERNET had conglomerated all the articles into a single file, leaving the user no option to choose an article. Moreover, I noticed that the program takes any 80 character line and turns it into a 79 character line and a 1 character line. The result is unreadable. 8. HOMEGROWN SYSTEMS ____________________ Nothing that you write at your local site will ever be used anywhere else. Anything you have done that is easy, someone else has also done, in a different and incompatible way. Anything that you have done that is hard required you to use too many special features of your "standard" UNIX system and its "standard" libraries and "standard" include files and "standard" file system. And then there's the special local graphics format and the special interface to the local printer. If you have many "foreign" users, most of them will never see what you do. Those who use your system will complain because it's not like the one they're used to. ........................................................................... 9. Conclusions about the User: _____________________________ Users have different ways of working, and different needs. A single program cannot anticipate or service all those needs. Experienced users want access to more information, and they want control over how they search it. They are offended by clumsy systems that are interposed between them and the information they want. Naive users want help and reassurance. They cannot discriminate between important information and factoid information. They need to have a "chatty" information system. A user has a "budget" of time and patience. A documentation program must get its foot in the door by emphasizing its simplicity and transparency. Its added features must be hidden or inobtrusive. The first time a user tries a documentation program will be the last time, unless the program is clean, familiar, consistent, logical, and requires no more than the appropriate amount of user effort and thought. 10. Conclusions about the Documenter: ___________________________________ If I could hire one extra person, I would hire a good writer. I would assign that person to read and rephrase our online MAN pages, and to rewrite our most heavily used online documents. If I could hire a second person, I would hire an "adequate" programmer with a good sense of how to write user interfaces. I would ask that programmer to create: * a decent bulletin system for announcements by staff. Important messages cause a headline to be sent to all users. The user controls how much the bulletin system intrudes. Bulletin messages are also visible as documents. Users may request bulletins be mailed to another address. * a search program that is an improvement on GREP. First of all, it knows beforehand where to search. Search the document area, the newsletter area, the man pages, the bulletins, and any other places where a user's eyes might have run across readable text. Secondly, it knows how to search. It will accept approximate matches. It is not case sensitive. It ignores special characters, punctuation, and new lines and hence can find "Linear Algebra" or "Partial Differential Equations". It does not require that a documenter mark up the text with keywords. It scrolls, it pauses, it offers to quit, or to examine a recent match more closely before proceeding. Third, it knows synonyms and related phrases. This requires the documenter to compile and maintain a list of keywords that may be related. For instance: minimization/maximization/optimization/ linear programming/least squares. NAG HELP program SLATECDOC program IMSLDOC DOCVIEW FIVE CONTRADICTIONS OF DOCUMENTATION Users are knowledgeable: What does it mean when it says the network is unreachable? Keep all information "local" Give the user no more than is needed. Make examples specific. UNIX is a standard operating system. Both UNICOS and ULTRIX allow us to add our own MAN pages out in /usr/man/manl ULTRIX expects TROFF input, and will reformat the pages, even if plain text. Users want formatted output. User terminals vary widely. Computers don't properly handle all terminal settings. BOLD at work is gibberish at home. Can't search PostScript output. Just because it says ".TEX" doesn't mean you can do anything with it! X-window: can't open screen, can't find font... The Vendor understands your position: Step 1: Create an account for a user named "S" Step 1: Requires the following privileges: CMKRNL, SYSNAM, SETPRV, SYSPRV, TMPMBX, and NETMBX. Step 1: Mount the tape on the Cray. Step 1: Type "INSTALL". Step 1: Create a large subdirectory of your home directory. Step 1: Requires System 6.0.5, Hypercard 2.0, and the Palatino fonts. May not work on Macintoshes with less than 4 MB of memory. Step 1: Modify the following script to suit your situation. Step 1: Enter the following 46 digit password. Step 1: type Make The Plight of The Documentor: A technical writer? A program documenter? A programmer who is not unable to write? A writer who is not unable to program? Useful tools: Remove trailing blanks from a document. Move margin of a document. Remove control characters. Force wrap of long lines. Vendor Online Documentation: Cray Man pages DOCVIEW CM Man pages IMSLDOC SLATECDOC NAGHELP Minor inconveniences don't matter: Always remember to set your terminal to vt100 before running this docu prog... Just look in /afs/psc.edu/common/usr/local/man/manl/*.l for the man page. If you try to print this file from machine B, but the print request is carried out by machine A, you will get a different file. In order to install documents, just log in again as the privileged user. You may have to run TEX a few times until the number of error messages no longer decreases. Then you're done.