From owner-freebsd-questions Wed Apr 4 4: 0:18 2001 Delivered-To: freebsd-questions@freebsd.org Received: from dire.bris.ac.uk (dire.bris.ac.uk [137.222.10.60]) by hub.freebsd.org (Postfix) with ESMTP id 08ABB37B725 for ; Wed, 4 Apr 2001 04:00:15 -0700 (PDT) (envelope-from Jan.Grant@bristol.ac.uk) Received: from mail.ilrt.bris.ac.uk by dire.bris.ac.uk with SMTP-PRIV with ESMTP; Wed, 4 Apr 2001 12:00:09 +0100 Received: from cmjg (helo=localhost) by mail.ilrt.bris.ac.uk with local-esmtp (Exim 3.16 #1) id 14kl0c-0002aU-00; Wed, 04 Apr 2001 11:59:30 +0100 Date: Wed, 4 Apr 2001 11:59:30 +0100 (BST) From: Jan Grant To: Dave Rideout Cc: FreeBSD Questions Subject: Re: Documentation In-Reply-To: Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Sender: owner-freebsd-questions@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG On Tue, 3 Apr 2001, Dave Rideout wrote: > I know this might be a little off topic, but I am going to ask, because I > respect the decisions of a lot of people on this list :) > > My boss wants our IT system to be thoroughly documented. Is there an > industry standard way of doing this? > Or a template that I can look at? > > Thanks for your help, sorry this is off topic Again, depends on what he means. ISO9001 "quality assurance" requires you to identify any process and document the procedures in it. Common sense means you ought to be keeping notes on stuff anyway, and there are a number of routes to go down. Simplest is a shared mailbox for sysadmins to dump stuff into (or GNATS) - to tarck day-to-day operations. This is a good place to start looking if you want to distill operational procedure into some other format. Apart from that, my only advice would be not to worry too much about looking into ISO9001 much further: it doesn't give very much (or very good) practical advice about _how_ you go about writing documentation. Docbook is as reasonable a format as you might want; you can retarget docbook at pretty much anything. What's your boss after? He might be after something like: D101.041 "Adding a new user account" Policy: A user must have appeared on the payroll system before an account can be issued. In that case, you will receive a form F43 from Payroll indicating the new user's name, department, ... Procedure: The user should be registered in the "USER" database which generates all accounts. All mandatory information on form F43 "New account request" must be supplied. This is done as follows: ... - which, frankly, is a complete drag. Advice: WRITE STUFF DOWN, keep it in a common place, have everyone contribute to it, manage your documentation with a revision control system, hire a young an as-yet unjaded PFY and give them the job of turning your mailing list into the above rubbish. -- jan grant, ILRT, University of Bristol. http://www.ilrt.bris.ac.uk/ Tel +44(0)117 9287163 Fax +44 (0)117 9287112 RFC822 jan.grant@bris.ac.uk On modesty: whoever said "it's hard being perfect" obviously wasn't me. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message