Tech writers spend a lot of time getting it right. So when an engineering team decides to implement a new command-line option, the tech writer has to get the right information of value to users. Here are some guidelines that I use. The main focus here is on compiler options, but this could apply to other applications as well.

Interface:

Give detailed syntax for the option. For example:

-xprofile_ircache[=<path>]

in general, we use ;

[stuff]        to indicate optional tokens
<thing>    to indicate place-holder, like <filename>
{a|b|c}      choice between one
[{a|b|c}]    optionally choose one
...              a list of arbitrary length eg a,...,z

PURPOSE:

• Explain the intended purpose of this option.
• Explain why the option should be used.
• Explain when the option should be used.
• Explain when the option should not be used.

EXPECTED BEHAVIOR:

• List each sub-option or argument and explain its effects.
• Is the option valid in all situations or on all platforms; when is it not valid?
• If valid for more than one platform or architecture, are there differences in behavior?
• Are there other options that when used together would change the behavior of this option?
• Do multiple references accumulate or override? For example, does
           -xthing=a -xthing=b on the same command line mean -xthing=ab or -xthing=b ?

DEFAULTS:

List the first and second defaults. First default is taken the option does not appear on the command line. The second default is taken when the option appears but without any suboptions.

WARNINGS/PRECAUTIONS:

Can anything bad or unexpected happen if this option is used correctly as intended, or incorrectly? Are there strange edge cases to be concerned about? How would the user identify such edge cases and unexpected behaviors?

MACRO EXPANSIONS:

If this option is a macro standing for set of other options, list what it expands into, in detail.

INTERACTIONS:

How does this option interact with other options? Does it change the behavior of other options and vice versa? Are there options that cannot be used along with this option, and, vice versa, should this option not be used if these other options are specified?

SCOPE:

If this is a compiler option, do all files have to be compiled with this option, or is just one ok? Does the main program? Any special instructions for compiling and linking in separate steps, or linking with libraries compiled with or without this option?

STABILITY:

Should the documentation warn about the stability of this feature? That is, will the implementation of this feature change in subsequent releases of the software?

EXAMPLES:

Show many usage examples, and explain the expected behavior. Provide MANY examples.

So where am I in this story now? Let's see... 1968, June 5, and I'm flying into San Francisco Airport with 60 boxes of books and everything I own, to take a job at the University of California Lawrence Radiation Lab (now Lawrence Berkeley Lab) computer center. But if you want to read this in the right order, you need to scroll down to part 1.

I started working at the LRL Computer Center, up on the hills above the Berkeley campus in July, 1968. I stayed there 13 years. And for most of that time I was responsible for maintaining the compiler (FORTRAN), assembler (COMPASS), linker/loader, I/O libraries, and related stuff. I also served as user support and wrote a lot of the user documentation.

By '68, CDC had given up on its futuristic SIPROS operating system and was forced to adopt the system developed by the engineers in Chippewa Falls (Wisconsin) under Seymour Cray. It was known simply as COS and was a productized version of the raw system we started using at NYU in '65. Still, input into the system was cards, output on paper or tape or punched cards. It would be another 5 years before display terminals appeared.

The picture above was taken in 1971 (by my Dad on a visit from NY, which may explain the sunglasses.) But note the typewriter. I was the only one on the staff with a typewriter, on which I wrote articles for the center newsletter and printed (xeroxed) documentation. Note also the bound listings on the desk and shelf. The shelf has the listing of the CDC 6600 assembler, COMPASS, and the RUN compiler.

What you can't see is the card file to my left. It held trays of cards. But by '71 source code management had progressed from decks of cards to source files on tapes and a program called UPDATE from CDC. UPDATE was an ancestor of SCCS on Unix. Now the update instructions ("replace card 248 in deck XYZ with the following cards") were punched on cards and fed into the card reader with the job control cards that read the source tape and generated a new version of the source program. This is how we maintained the thousands of lines of the compiler, assembler, etc.

What I enjoyed the most of my years at LBL was the community of scientists, engineers, mathematicians, and programmers. You never knew who you would meet in the cafeteria, including Nobel prize winners. The systems group was quite small, maybe 5 full-time programmers (one of them is also now at Sun, Marty Itzkowitz , and ironically just like at LBL, his office in Menlo Park is still next to mine).

In March of 1971, I and a small team of programmers and computer operators went to Chippewa Falls to run acceptance tests on the CDC 7600 that was installed at LBL later in the year. The 7600 was a big improvement on the 6600, running 4 times faster at 27.5 nanoseconds, and featured multiple pipelined functional units, which meant that you didn't have to wait for one multipy to end before you started another.

Also, by this time CDC had developed its SCOPE operating system, based on limited time sharing and remote job entry (satellite card reader and printer stations linked over phone lines). But after careful review, the LBL systems group decided to further develop the COS system for its own needs, and called the derived operating system BKY. And my job was to keep the compilers and tools that CDC made available under SCOPE running under BKY.

One great advance was CDC's FTN compiler, which replaced RUN. FTN did some amazing scalar optimizations. It knew a lot about instruction timing and scheduling. Finally we had a compiler that would produce code that ran as fast or faster than equivalent code written by hand in assembler. But maintaining FTN was a lot different than maintaining RUN. It was no longer possible to call up the compiler programmer and report a problem, and then get a patch in the mail in a few days. Things had gotten very corporate. Filing a bug against FTN required filling out a form, include test source code and listings, and mailing it to CDC Sunnyvale. Eventually a distribution tape with a new compiler would be issued with a list of fixed bugs. Hopefully, your bug would be on that list. For me the interesting part was creating a software environment in which the compilers and tools could live that interfaced the BKY system. Altho at the programming level BKY and SCOPE were not that far apart, there were always problems as SCOPE got more mature. And, keep in mind that all systems programming on these systems was done in assembly language.

...to be continued