Surviving Documentation Systems When I use a word, it means exactly what I wish it to mean. The Question is, Which is to be the Master? SLIDE 0) Introduction SLIDE 1) The Story So Far SLIDE 2) Why did we love MAN? SLIDE 3) Why did we hate MAN? SLIDE 4) What's gone wrong? (New challenges) SLIDE 5) How can we survive? SLIDE 6) How can MAN survive? SLIDE 0) Introduction I've altered slightly the original suggested title of my talk. I'm interested in personal survival, how we as documentors can hope to remain healthy and sane into the next century. We survive our documentation systems. However, I believe we have limited control over our fate. I don't know what the documentation system of the next century will be, but I know it will be called MAN. Documentation systems themselves survive. So perhaps I should rephrase the title again: Peacefully Coexisting with Documentation Systems But since we can't restrain our tinkering instinct, my last version of the title would be: Peacefully Evolving with Documentation Systems. SLIDE 1) The Story So Far Once, in a better world, there was a single computer with a single operating system, a single file system, and two teletype terminals which used paper. In order to remind users of the way to use the awkward commands, a set of notes was made available, through the MAN command. The structure and format of these notes became standardized. By typing "man cat", one could see the purpose of the CAT command, a detailed description of its workings, every possible way to modify its workings, and an example or two. No one had to prepare manuals that users would have to lug around. SLIDE 2) Why do we love MAN? 1) Having information online meant that documenters could correct or improve it instantly. 2) Whenever we got confused on a new UNIX system, we always knew where to turn for help. 3) The standard format, for all commands, across all UNIX machines, meant that you knew what to expect. 4) Assuming you know PG, you can search and redisplay. 5) A user can easily creating a personal file copy of a MAN page. It's done the same way you would do it for any UNIX command. 6) The system was locally extensible. The documenter could put any item of text out in /usr/man/manl, and MAN would display it. SLIDE 3) Why do we hate MAN? 1) Strictly limited to system commands. No coverage of keywords, important files, phrases, concepts. If you find a word in a MAN page, like "$HOME", which is printed in boldface, you might assume that it is an important concept which you'll never find defined in a dictionary. So where is it defined in the MAN system? What about important files like ".login"? Or phrases like "C shell"? 2) Users expect a documentation system to be so easy to use that they don't have to think. But the basic MAN interface is of a very long piece of paper that you can only scroll a line or a page at a time. Most users are not interested in learning MAN commands (/ for search, etc), because they are not common or natural. And who types "man man" to find out the abilities of MAN? 3) The documenter can't break MAN information down into logical subgroups that a user can choose to see or skip. The information is presented "flat". The only "jumping" a user might try is to search for standard entry headings like EXAMPLES or BUGS, but these are not always supplied! 4) No summary of contents or overview is available, not even information about whether the EXAMPLES or BUGS fields are available. 5) Screens and paper are two entirely different mediums. Users scan a screen, and study a paper. A single MAN page is not appropriate for both. Historically, the MAN page style is too terse, cluttered, and unfriendly for online use, without being expansive enough to allow clear discussions in printed form. 6) MAN has a limited keyword search ability: Current page can be searched forward via "/KEYWORD" You can't search the full text of all pages, only the one-line definitions using "-k". 7) Most MAN pages are very hard to prepare (TROFF, anyone?), and require extensive experience to properly format and display. 8) No overview, no sense of what's important. SLIDE 4) What's gone wrong? (New challenges) 1) In the good old days, there weren't that many commands, and there weren't that many switches. Now there are hundreds of commands, and some, like the CF77 command on UNICOS, have so many switches that upper and lower case letters aren't enough, and switches now have subswitches. MAN offers no choice but to list every one of these switches in alphabetical order. Most users never find the information they want. 2) Command names have gotten more complicated. MAN can only document "thing" if "thing.l" is a legal file name. So, for instance, we cannot document the AFS file system commands, such as "fs checkserver" or "fs listquota" so that a user could type "man fs checkserver". Nor can you document "$HOME" or "Use of *". 3) TROFF is not a viable document formatting language. TeX is the common language of document formatters, though no one is going to put a TeX processor inside of MAN! Workstations allow users to resize their windows, and alter other display characteristics, but TROFF (and TeX, for that matter) assume that they are preparing output for a fixed size device: whatever the system thinks you have. Resizing the screen won't have the right effect. 4) The user base is more diverse. They aren't all hackers any more. Many are naive, and unfamiliar with UNIX and programming. 5) The traditional writing style used in MAN pages is so terse, dry, unhelpful and unfriendly. A user asking for help can sense instead smugness, arrogance, or even contempt. SLIDE 5) How can we survive? Given that MAN will outlive and outgrow us, how can we influence it for the better? Minimize and focus our efforts: Never try to replace a system MAN page. Don't format pages. Simplify and standardize: Add MAN pages for local software (or hardware or topics). Use a consistent layout. Be brief but conversational. Move details from MAN pages to online documents. Users do not expect (and cannot cope with) detail in a MAN page. Users expect detail in a document, and have well developed skills for searching, reading, extracting, printing, or otherwise manipulating a document. SLIDE 6) How can MAN survive? Discard all current MAN pages, replacing with: 1) A "help" page no more than 72 lines (3 pages). 2) Old MAN topics cut down to One line definition, Purpose, Features, Examples. 3) Add universal search for words and phrases. 4) Write up full details in online text documents. MAN program should be able to present MAN pages for different operating systems. My workstation should be able to retrieve MAN pages for YMP, or CM2, or the workstation itself, assuming they are all available in a common file system. More flexibility in MAN command. On DEC ULTRIX, can only search man 1...man9. File name must end in ".l". Cannot handle upper case or mixed case request if file name is lower case. TROFF is dead. The MAN program should accept plain text or TeX, and preformat it to 80 column output.