Hi All, I come from the z/OS and z/VM world as a technical writer experienced in documenting mainframe system applications. I'll looking here and at www.tldp.org to figure out how to do the same for Linux applications used by system programmers and administrators.

Regards,
Jeff Van Arsdale
Technical Information Architect
CA technologies

It seems that after many days, no one has replied to your post. Perhaps, like me, they are unclear as to what you are looking for.

Not knowing your level of familiarity with linux, I must ask if you are aware of the "man pages' that provide documentation for most system software commands? Are you aware of the 'history' command that allows one to retrieve a long list of previously issued commands in a terminal window? Sorry if you a way beyond this.

I am neither an administrator nor a systems programmer, but I do program in higher level languages and write applications software documentation occasionally.

1 members found this post helpful.

Hi and thank you for the reply. This confirms my own thoughts that a portion of the technical communication industry has an incomplete understanding of the 'end-user' experience, thinking that it's always a GUI experience. The manpages, TLDP.org, z/OS, z/VM, and Linux/UNIX doc and online help is simply a difference environment than the GUI world. I've run across this theme in several places. Said here by Machtelt Garrels in "Introduction to Linux":
"2.3.1. Be warned
GNU/Linux is all about becoming more self-reliant. And as usual with this system, there are several ways to
achieve the goal. A common way of getting help is finding someone who knows, and however patient and
peace-loving the Linux-using community will be, almost everybody will expect you to have tried one or more
of the methods in this section before asking them, and the ways in which this viewpoint is expressed may be
rather harsh if you prove not to have followed this basic rule."

Which to me, is another version 'teach a man to fish' a concept lost on many nowadays.

When I was an administrator (that that goes back to RSX-11, VMS, AT&T System Vr2, SunOS/Solaris, Linux (in various forms) UNICOS...

Keep a notebook - write anything you do down.. and include side notes, complaints about finding things, where you found them... Anything you do more than once, add a new entry (referring to the previous one)...

Then about once a month (or whenever there isn't a fire to put out) transcribe/consolidate the notes into a "System Operational Procedures" (SOP) book that removes the cussing recorded, and makes a more formal presentation of the procedures identified (AND include references you found while fixing the problem). Put decent titles, table of contents... and if you are ambitious, add cross references. The nice thing about the cross references is that when working with multiple different systems, you can discover common procedures... and thus simplify the SOP documentation.

One of the BIG problems is getting your hands on the sites security documentation. This is a problem because frequently there hasn't been one written, or the one written is a "policy statement" which does nothing to identify how that relates to system administration. Thus you also end up being a translator... And that becomes the first section of the SOP - and remember, this first section SHOULD be approved by the site/facility managment. I say "SHOULD" in caps because without it you can't get the backing of management for what you do, or for the procedures in the SOP.

The nice thing about working with/in a government organization is that they do understand CYA for such documents. Outside of government organizations, it becomes much weaker - and subject to "I didn't mean you could do THAT"... where they just don't remember telling to explicitly to do "THAT".

The nice thing about an actual written document (above and beyond a wiki) is that it becomes possible to print it, and hand it to them (dated of course). Then they can't say they weren't informed ahead of time when you carry out a procedure (even if it doesn't quite work, for any reason). It also helps to prevent forgetting a step. Using a loose leaf binder also allows you to insert sheets with additional notes... to be merged in later.

It also helps to be able to hand the book to someone else to be able to use.

Things that go into the book: backup procedures (obviously), installation procedures, decommission procedures (can be very important for security, proper purging of disks and such), patch procedures, startup/shutdown, adding/removing users, adding/removing software, network configurations, BIOS configurations, recovery procedures used, system failures and recovery (can be a big one).

One thing I managed to do during an emergency was to direct an operations staff - Each task group (there were about 5) got an operations person to do nothing but take notes on questions, answers, decisions... and mark the entries with a timestamp (don't forget to get everyone on the same time). This can also be put into the SOP, but the purpose of the procedure is to be able to consolidate the log reports from the different tasks that can be presented to management. This provides both a CYA for the general staff (and yourself), it ALSO provides a CYA for the site in case legal complications arise (didn't in my case - it turned out to be a misconfigured/installed firecontrol panel that decided to shutdown all power to the center and set off a halon discharge, which was prevented by realizing there was no fire and issuing a reset) The power failure had already happened. Another was finding out the emergency generators took too long to power up after a loss of power (had to QUICKLY power of several servers to cut the battery load).

So having a procedure in place before the emergency helps cut out a LOT of delay.

And remember, that SOP has to support the first section.