On Mon, Mar 1, 2010 at 7:56 PM, <josh+s...@eldertimes.us> wrote: > So, I suspect like at least a few of you, I suck at documenting what > I've done. Unless I make a conscious effort to do it as I go along, > it often doesn't get, as the next fire takes priority.
It's not a panacea, but knowing that you need to make a conscious effort to do it as you go along helps. The documentation doesn't have to be perfect or pretty, but it does need to be done. I try to follow the "hit by a bus" rule -- if I get hit by a bus, have I left enough documentation that someone who's tasked with taking on my role can do a semi-decent job? In my experience, if I don't document as I go along, it doesn't happen and/or it doesn't have all the little bits of info that you know while you're in the middle of the project. My approach is to document everything possible, whether it's a minor request or a major project. Of late, I've primarily being documenting in a wiki, but I might also attach a typescript of a specific session or a text file of commands executed and results in addition to the general text of what I've done. I try to document to the level that you could give anyone my docs and they could perform the task even if they knew nothing about it. It takes more time, but I also do it for myself -- 18 months from now when someone asks me about the installation of system xyz, I can refer to my notes. I find that it doesn't take that much time to copy/paste commands and their results while I'm performing the task -- the trick is to get into the habit of doing it. All of this is especially key if you're doing something that you don't frequently do or won't be expected to do regularly. > But what about keeping up with documentation as tasks are accomplished, > new systems are stood up, etc? What tips do folks have for getting > better at documenting in their daily tasks? I have a base template for all systems -- specific data gets recorded -- for example, if I'm building a new system, I'll record serial #, MAC addresses, IP addresses, CPU info, RAM info, disk space, versions, etc. For a *nix system, I save off info on what packages where installed by default, what packages I removed, what packages I added. For network gear I save off initial configs with notations as to why each thing was configured in the way that it was. Using a wiki system, I have individual pages for every system and each system has links to pages for each application or service that's been configured for the system. If you're using a ticketing system, you can use that to assist with your documentation. For example, there's a big disparity between marking a ticket solved with notation "Done." vs marking it solved as "These two software package versions conflict with each other badly so we have installed package #1 version X and package #2 version Y," or "Someone goofed and enabled portfast on port Gi1/0/24 and that made things unhappy." The former won't help you 6 months from now, but the latter might. Hope this helps, M _______________________________________________ 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/
