Date: Tue, 3 Apr 2001 22:46:22 -0700 From: "Ted Mittelstaedt" <tedm@toybox.placo.com> To: "Dave Rideout" <drideout@cssnow.com>, "FreeBSD Questions" <freebsd-questions@FreeBSD.ORG> Subject: RE: Documentation Message-ID: <000a01c0bcca$94352360$1401a8c0@tedm.placo.com> In-Reply-To: <NEBBKBOMILGEKHIBFECLKEGHCHAA.drideout@cssnow.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Speaking as a documentor I want to caution you that before you write a scrap of documentation, you need to go back to your boss and ask the question "what goal is this mandatory documenting supposed to accomplish?" If your boss is at all competent, he should have no problems with answering this. But, just in case he's one of the "I read your supposed to document things in today's CIO magazine" people, here's some suggestions: 1) Your boss got a call from the HR manager who told him that she is aware that you are rustling up another job elsewhere and he wants to get the system documented before you jump ship. 2) Your boss is thinking of making a career move himself and wants some free training so that he can put "Managed UNIX system admins" on his resume and not look like a fool when they start asking questions about it. 3) Your boss is uncomfortable with your stories of your Friday evening drinking binges and figures your running pell-mell into an intimate encounter with a neighborhood utility pole and wants to get a knowledge dump before your suddennly permanently unavailable. 4)Docs are needed because the system is running so smoothly that the secret plan is to fire all of you guys and replace you with $20K-a-year newbies and they want to make sure docs exist for the rare times that they have to hire a consultant to come in and actually do something. 5) Generating pretty-looking glossies to wave in front of upper managers who couldn't understand system documentation if they saw it, and are going to be very upset if there's not a lot of colored symbols, diagrams, and other "system documentation looking" things in it, and are pressing your boss to justify why the IT department is so large. 6) Thick, heavy, impressive-looking tomes are needed to support a political grab by your boss for next-year's budgetary increase. Anyway, joking aside, you have to know what the point of documenting the IT system is before knowing what part of the IT system should be documented. If the goal of the docs is to help other managers in the company understand what resources the IT group has built, those docs are going to be very different than a set of docs intended for use in disaster-recovery. This is why it pays to make IT systems as self-documenting as possible. If you guys have been putting hundreds of hours of custom-configuration into your IT system then that custom-configuration is a company asset, and it's frankly worthless if it only exists in the brains of the 3 admins that did it. But, if you have been faithfully making patchfile diffs and storing them off and documenting why this particular diff exists and what it does, then if the whole works is backed up regularly, then your pretty well covered. Ted Mittelstaedt tedm@toybox.placo.com Author of: The FreeBSD Corporate Networker's Guide Book website: http://www.freebsd-corp-net-guide.com >-----Original Message----- >From: owner-freebsd-questions@FreeBSD.ORG >[mailto:owner-freebsd-questions@FreeBSD.ORG]On Behalf Of Dave Rideout >Sent: Tuesday, April 03, 2001 8:39 AM >To: FreeBSD Questions >Subject: Documentation > > >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 > >Dave > > > > >To Unsubscribe: send mail to majordomo@FreeBSD.org >with "unsubscribe freebsd-questions" in the body of the message > To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?000a01c0bcca$94352360$1401a8c0>