On 08/10/2010 07:55 PM, Jefferson Cowart wrote: > My #1 recommendation is to have a wiki of "checklists". People don't >> like writing documentation but they are ok with writing checklists. >> Some standard checklists to write are: >> 1. things we do for each newhire. >> 2. things we do when an employee is terminated. >> 3. how to (allocate space in the machine room, set up a new server, >> deploy a workstation, add to the puppet configuration, etc. etc.) >> 4. how to respond to the monitoring system when it pages you: For each >> page that you can receive, list the reaction steps. The last step >> should always be "if all that failed to fix the problem, escalate to >> so-and-so." If so-and-so feels he/she is getting called in the middle >> of the night too much, ask them to improve the checklist. Encourage >> people to write the checklist when they add the alert rule to the >> monitoring system. If someone won't or doesn't write the checklist >> for a particular alert it just means they have agreed to be called in >> the middle of the night every time. >> >> These checklists will grow and improve over time. Every time you have >> an outage, augment the checklists that would prevent that problem in >> the future. > We already use a mediawiki install for hosting documentation, so I think > this can fit in nicely. It has a few checklists on it already, but we > can certainly improve them. > > On that note, any suggestions on how to get people to write [good] > documentation? Others in our teams seem to be very resistant to writing > even basic documentation. (There are a couple services we provide that I > don't have documentation on what system hosts the database.) I'd guess > I've written 90%+ of the documentation on our wiki. While everyone > agrees it's a good idea, no one makes the time to write it. A few ideas, obviously these will need tweaked to suit your environment:
1) If you're in charge of performance evaluations, make documentation a condition of them. At a previous job there were a few categories I had to fulfill if I wanted to get my annual bonus, one of which was making sure I'd documented anything I'd worked on. Any failure to document anything meant that staff categorically would not get a bonus. 2) Nothing goes live without documentation. Lay out a deployment checklist for services, an early step being documentation. The project does not get signed off by you until the documentation is written, or if you can put it in the process earlier, not authorized for deployment until it's documented. If that means holding open a job ticket, or causing an inconvenience to another department because their task isn't complete, so be it. Your staff should soon learn to make sure everything is documented. (I'd love to use that method here.. I'm tired of troubleshooting undocumented java web-apps at 11pm) 3) Now you've got management authority over them, set up dedicated documentation days. No other work is to take place, period (maybe allow one staff member, maybe yourself, to handle emergencies). Any time spent doing emergencies instead of documentation must be made up by staff member involved. I can't see anyway in which it's not going to make you unpopular, but you'll just have to persevere until the staff wake up and realise that good documentation aids them significantly. Paul _______________________________________________ Discuss mailing list [email protected] http://lopsa.org/cgi-bin/mailman/listinfo/discuss This list provided by the League of Professional System Administrators http://lopsa.org/
