Visit Jeremy's Blog.
Go Back > Forums > Linux Forums > Linux - Newbie
User Name
Linux - Newbie This Linux forum is for members that are new to Linux.
Just starting out and have a question? If it is not in the man pages or the how-to's this is the place!


  Search this Thread
Old 08-19-2013, 02:51 PM   #1
LQ Newbie
Registered: Aug 2013
Posts: 2

Rep: Reputation: Disabled
researching how to document system programmer tasks

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 to figure out how to do the same for Linux applications used by system programmers and administrators.

Jeff Van Arsdale
Technical Information Architect
CA technologies
Old 09-01-2013, 08:15 PM   #2
Registered: Jul 2009
Location: Murfreesboro TN (United States)
Distribution: Ubuntu 16.04.3 and 14.04.5, Debian 8.9 and 9.2
Posts: 131
Blog Entries: 36

Rep: Reputation: 26
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.
Old 09-09-2013, 08:55 AM   #3
LQ Newbie
Registered: Aug 2013
Posts: 2

Original Poster
Rep: Reputation: Disabled
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,, 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.
Old 09-09-2013, 01:38 PM   #4
Senior Member
Registered: Dec 2012
Location: Washington DC area
Distribution: Fedora, CentOS, Slackware
Posts: 4,711

Rep: Reputation: 1279Reputation: 1279Reputation: 1279Reputation: 1279Reputation: 1279Reputation: 1279Reputation: 1279Reputation: 1279Reputation: 1279
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.


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off

Similar Threads
Thread Thread Starter Forum Replies Last Post
system crontab not carrying out tasks... nass Slackware 9 10-24-2007 05:29 PM
basic system admin tasks kc3377 Linux - Server 2 04-25-2007 11:24 PM
LXer: Linux System Administration: First Tasks LXer Syndicated Linux News 0 04-22-2006 07:21 AM
Commonly AIX System Admin Tasks DriveMeCrazy AIX 2 12-07-2005 08:57 PM
UNIX multi user,tasks system ? why ? my-unix-dream Linux - Newbie 5 06-27-2004 04:51 PM > Forums > Linux Forums > Linux - Newbie

All times are GMT -5. The time now is 09:46 AM.

Main Menu
Write for LQ is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
Facebook: linuxquestions Google+: linuxquestions
Open Source Consulting | Domain Registration