I've been tackling documentation at $work lately ... and here's what I
found works for me:
Changelog ( A blog for all team members)
Pattern Library
Runbooks
Services
Service Name (and general description, links to server runbooks)
Procedures
Servers
Server Name (maintenance log, links to service runbooks)
Changelog - Used for system outages, changes to systems, and general updates
Pattern Library - These are general guidelines used in-house, they are
not rigid procedures.
Runbooks - Collections of checklists and procedures
Service Runbooks - Installation documentation
Server Runbooks - Mainly maintenance logs and links to service runbooks
This may seem a little baroque but I didn't plan it this way. Best
advice for documentation: Just do it. Document as you go, worry about
organization latter. If you don't want to install a wiki, jsut use
plain text files and grep.
On Mon, Mar 8, 2010 at 10:00 PM, Tom Limoncelli <t...@whatexit.org> wrote:
> On Tue, Mar 2, 2010 at 5:14 PM, <berg...@merctech.com> wrote:
>> What does Tom have to say (see Time Management for Sysadmins or The Art &
>> Practice...)?
>
> People have made a number of good points already: Know your audience,
> figure out your purpose, use something that makes it easy to do (Twiki
> is my favorite, BTW).
>
> The hardest part of doing documentation is getting started. It is
> hard to decide what to document, it is hard to tell when you've
> documented something well enough. It is hard to get motivated.
>
> The motivation that works for me is to document things that I hate to
> do, and document them in a way that will enable other people to do
> them. That way picking things is easy, knowing when I've documented
> them well enough is obvious, and the motivation is built-in.
>
> I usually document things as a bullet list:
>
> NEW EMPLOYEE CHECKLIST:
> + Create account in Active directory
> + Order new PC
> + Install PC at the desk it will be used.
> + Load PC with OS and verify account works.
> etc.
> etc.
>
> Each of those things may be a link to another document which lists the
> actual steps, or just to a list further down the page.
>
> NEW MACHINE CHECKLIST:
> 1 Unpack and install at desk.
> 2 Netboot to wipe and reload operating system.
> 3 Make sure wireless mouse works.
> 4 Log in, change the following settings:
> a. foo
> b. bar
>
> I'm not good at doing things I dislike to do. I get bored and make
> careless mistakes. Therefore, I use my own checklists so that I make
> fewer mistakes. It also means I don't have to think as much. I save
> my brain power for other, more important, tasks.
>
> Each item in a checklist has a goal, "Netboot to wipe and reload the
> OS", and a "how to" section (Boot while pressing the F12 key, select
> "boot from network", select "Windows 95" from the menu). The "how" is
> usually listed inline, or as a link to another page. The goal should
> be something a manager would understand, the "how" is something a
> technician should understand. If management wants to change a process
> they should add new "goal" items and let me work out the "how". So,
> if they have been getting complaints about the wireless mouses not
> working, they might add a goal like #3 above.
>
> The lists are easy to edit on the wiki, thus I can update them on
> demand. Something like #3 above might be added after we get a rash of
> faulty mouses. #4 might be added because we haven't automated those
> things, or built them into the Netbook procedure yet, so they get
> listed there as manual steps until they can be rolled into the
> automated system. These kind of things result in the process getting
> better over time. (Lee Damon recently reminded me that this is akin
> to the business practice called "continuous improvement".)
>
> Because I keep good documentation about the processes that I don't
> like to do, when we do have budget to hire a new person, I have their
> job description practically written. Their responsibilities will be
> [insert all the checklists I've written so far]. Their training will
> involve being walked through each checklist. I can evaluate their
> process by gauging how fast they get up to speed at doing the
> checklists. I can evaluate their readiness for promotion to "senior
> sysadmin" when they start creating checklists for other people.
>
> It is hard to automate something until it is documented. Having
> checklists means I have that documentation. Over time I automate the
> most painful steps, which is a lot easier than trying to automate the
> entire process. Heck, just leaving commands that can be
> cut-and-pasted is better than having to type them all the time.
>
> Lastly, because I know the basic tasks can be handled by someone else,
> I sleep better at night. I can take longer, more relaxing vacations.
> Even if I'm the solo sysadmin, I can usually train another technical
> person or friendly software developer to follow my checklists.
> Finally, I enjoy my job more because I don't feel "boxed in" nor do I
> develop a martyr complex because I'm the only one able to do important
> tasks.
>
> Tom
> a video that says all the above will soon be an episode on
> http://www.TomOnTime.com
>
> --
> http://EverythingSysadmin.com -- http://www.TomOnTime.com
> Computer and network administrators... Spread the word!
> LOPSA New Jersey Professional IT Community Conference
> New Brunswick, NJ, May 7-8, 2010 -- http://picconf.org
> _______________________________________________
> Discuss mailing list
> Discuss@lopsa.org
> http://lopsa.org/cgi-bin/mailman/listinfo/discuss
> This list provided by the League of Professional System Administrators
> http://lopsa.org/
>
_______________________________________________
Discuss mailing list
Discuss@lopsa.org
http://lopsa.org/cgi-bin/mailman/listinfo/discuss
This list provided by the League of Professional System Administrators
http://lopsa.org/
