One of my new projects at work consists of revamping the checklists used when employees join and depart the company. My memory may be fuzzy...I actually have a horrible memory...but the incarnation that has been used was my own concoction from back when I joined the company nearly a year ago. For awhile, as each new person joined (or left) I would refine the action items so something overlooked the last time would hopefully not be missed the next time around.
It become something more than a checklist; it mutated into a checklist of action items with a set of how-to instructions under each entry. We kept the final incarnation on an internal wiki system. A new person could tell that it was a dirty bit of work since the original checklist had a big old warning and link at the top telling the reader to go to another page that was updated and had more precise instructions on how to complete each step.
The finished list is one that I've been using for the past several months without much trouble. But things move on; more services are being added, the workflow for particular departments have added accounts they'd like added at hiring time, and as the company has grown the cross communication of who should be notified of what information for orientation has changed. The process has become on of the items that is a pain point, but only to the degree of an itch; people scratch it, are slightly irritated, but not irritated enough to warrant fixing the pain point...until next time, at which point the process repeats itself.
We also have a new system administrator in the team, and one of his central tenets to good systems administration practices is documentation, documentation, documentation. He's spent a good amount of time getting up to speed with our brand of Kool-Aid by revamping our internal documentation system; a side effect is reminding us of the technical debt we've created in our documentation practices. It's been a great motivator in getting my own checklist project updated. His work reminded me of something I'd lost sight of:
Your documentation isn't for you.
Adding new employees and disabling accounts had become something of my own niche. The documentation that had started out being a general list for anyone who would need to add employees became my own cheat sheet. The basics were there. But if someone new came along to do the job, the instructions didn't quite align with the exact steps needed to achieve the desired outcome. It was something I knew should be fixed but hadn't taken the time to do...until now.
To summarize a conversation Tom and I had one afternoon, "The goal should be to document and automate yourself out of the job. There's always something more to do."
My documentation wasn't really being used as documentation. It was a set of notes that I could refer to when trying to memorize the steps to reproduce a desired outcome. Gradually the steps became ingrained and the notes became more of a checklist that I would skim.
I also gradually gained a better understanding of what and why I was doing something. The documentation became burned into my head, and the notes masquerading as documentation fell into disrepair.
As I worked with the new and improved documentation I was surprised to see to what degree things were out of date. For example, our list of items to complete included provisioning a phone. We use Asterisk in-house, and each office has its own local server. Over the course of time, the newer offices had altered configurations for Asterisk, which automated more of the process and simplified the creation of accounts and phones.
I hadn't realized that at some point the New York system's documentation was out of date to the point of just being plain wrong; if someone else tried to follow those directions they would not have found anything resembling the sample entries they were supposed to follow.
I'm still in the middle of the checklist revamp. I'm trying to do it right, or at least better than before, which means it'll take some time; I'm doing an initial set of passes by literally documenting each step I take in creating new users and where appropriate I'm adding notes explaining why I'm doing what I'm doing.
Once I can follow the new instructions from start to end without a major hiccup, I'll identify points in the process where I'm missing information. I'll look for things that are now consistent requests for modifications to accounts...such as, "Bob needs to be on <XYZ> mailing list"...and roll it into the initial setup procedure. Yes, this means having to communicate with people who manage various areas hiring new developers and salespeople.
Then I'll look for procedural refinements. For example, I've created a new badge for the user...who does it go to? Do I give it to the office manager? The new employee's manager? Do I hold on to it until the employee comes to me for it? We need to formalize this process so everyone is on the same page and knows, when asked for Bob's badge, where to look for it.
Once finished, I should have a list that is thorough enough for anyone in our technical staff to follow in creating a new employee entry with minimal mistakes.
An unfortunate side effect is how thorough it is becoming. I'm not completely through every step, and already the list and explanations is eight pages. Not the kind of checklist most people would like to deal with just to add an employee.
So what is the right way to do documentation "right?" The stuff I'm working on should be thorough enough that someone new to the job should be able to follow them, and the notes help augment an understanding of the thinking behind some of the steps. It should also pinpoint places in the procedure that need work, whether it's updating images rolled to machines or identifying where we might be able to potentially automate parts of the process. The problem is that this becomes less a checklist and more a procedural how-to, and as people become familiar with the process they start to ignore the checklist parts of the process much in the way billboards become simply visual noise I barely pay any attention to anymore when riding along the freeway.
Should documentation be adapted for more advanced users? Or should it keep some level of detail for people to refer back to, or for training newer users, despite meaning you may have to maintain various levels of documentation and keep them in parity?
No comments:
Post a Comment