RE: [SAGE] Unix sys admin "run book" documentation standards and templates

[John LLOYD <jal@mda.ca>]

> If that was where I think you mean: That was due to my and 
> Hal Pomeranz's 
> thinking about this.  I had recently come from a company that 
> was heavily 
> into TQM, and the software group I worked in was undergoing ISO-9001 
> certification just then.  I adopted the term "work 
> instruction" from the 
> ISO-9000 universe.
> 
> We were thinking of going for ISO-9001 ourselves, in the sysadmin 
> organization at the new outfit, but somehow didn't get around to it.
> 

ISO9k is harder to apply to operations groups, as compared to, say,
manufacturers.  It is not impossible, of course.  The chief advantage to it
is that it is widely recognized.  The chief disadvantage is that it doesn't
really help you.  ISO 9k certification means that you have documented
procedures and that you can prove to an auditor that you follow them.

Our department is ISO certified and our procedures include a lot of steps
that read "evaluate the situation and do the right thing" [I paraphrase, of
course.]  Getting the procedures written down was the hard part and it was
useful.  The critical concept is to document what people actually do and not
try to optimize or define what they ought to be doing.  ISO 9000 didn't help
to improve our operation, only to codify it.

However, for a group that has a lot of undocumented procedures, undocumented
systems, concerns about diverse configurations and (unstated) concerns about
unmanaged risks, ISO 9000 is not a solution but perhaps a definition of an
end point.

I would suggest going back to basics:

 What is the real problem?  Is it concern about risks?  Is it concern about
possibly excessive costs?  Is it concern about quality?

Risks can be understood by identifying them and mitigating them (I am using
a system engineering definition of risk, not a financial or informal one.
See http://www.riskworld.com/BOOKS/topics/risksoft.htm for a list of books
on the topic.  I recommend the Karolak book.).

On the other hand, if quality is your concern, then you could try a
"top-down" re-engineering approach.  If you had to build the systems from
scratch, how would you do it and what would you get in the end?  The short
answer is two things:  a set of working systems and a set of documents that
describe them: what they are for, what they consist of, how they were built,
how to operate them, and how to maintain and modify them.  In short, the
requirements, the system design, the detailed design, operations guide, and
maintenance/support book.  At the end you have a set of systems and software
that provide your customers with exactly what they want, ie. a high quality
system.



--John