[If you are in the NYC region, I'll be speaking at PICC in May.]
(I originally wrote this for system administrators, but it applies to other fields too.)
The hardest part of writing 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.
Whether you keep your documentation on a wiki or in a subdirectory full of text files or a formal notebook, without motivation it isn't going to get written.
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. (See why that motivates me?) That way picking things is easy (I know what I don't like to do), knowing when I've documented them well enough is obvious (I know what my co-workers will understand), and the motivation is built-in (there are some tasks I really want to be able to delegate).
I usually document things as a bullet list:
NEW EMPLOYEE CHECKLIST:
- Create account in Active directory, LDAP, Kerberos
- Order new PC
- Install PC at the desk it will be used.
- Load PC with OS and verify account works.
NEW MACHINE CHECKLIST:
- Unpack and install at desk.
- Netboot to wipe and reload operating system.
- Make sure wireless mouse works.
- Log in, change the following settings:
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. The tasks go quicker. It keeps the checklist "fresh" since I can update it if I notice something has changed. By following my own checklist 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 7 for Sales" or "Windows 7 for Engineering" from the menu as appropriate).
The "how" is usually listed inline, or as a link to another page, or as a link to another checklist further down the page. ("How" is not shown in the above examples.) The "goal" should be something a manager would understand, the "how" is something a technician can do. If management wants to change a process they should add new "goal" items and let the technical staff 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. This keeps a manager from micromanaging and let's us technical folks exercise our creativity to reach that goal.
I prefer to use a wiki so that the documents are easy to update, even when I'm in the middle of following one. An item 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. Thus 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.
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.
P.S. My "Time Management for Sysadmins" class expands on these ideas. The next time I teach this class will be at LOPSA NJ PICC, May 7-8, 2010 in New Brunswick, NJ. I'll also be teaching another class and I've been asked to be the Saturday morning keynote. For more info: http://picconf.org