20070714

Making progress, leaving footprints.

It's a bit depressing to see that I'm down to about one blog per month. At least I'm making a bit of effort hre, as well as making progress on the other projects that compete for my time.

As I've changed jobs, I appreciate the 'Oral History Project' that most companies use to store and share knowledge about network infrastructure, legacy reasons for doing things, even network architecture. But, I only like them a little, mainly because they aren't a stable source. People leave companies, or even just transfer to other departments. Stories change with time, and details tend to degrade very rapidly. I like documents better. (That's one large reason I make my web pages, and keep this blog.)

I learned a long time ago, from two examples, that the time it takes to make some basic documentation is largely paid ack when you use the documentation 3-4 times. Whether it's time saved when you refer to it yourself at a later date, or whether it's time saved when you give the document to someone else, and they can do a task, without you needing to give them the information via storytelling and sitting with them while they do the task. (I won't put the example stories in this article, to save space. Maybe I'll post them in a separate article, if there is some demand for them.)

When I'm debugging a problem, I keep notes, usually in a 'notepad' or 'teach text' file. (Save the file with a useful name, and save it often during the project!) If I'm working on a device configuration, I keep a diary of the changes I made, in case I need to revert anything. I also paste in any error messages I get during the process.

BUT, here's the message for this blog... During the process, I make notes about some of the useful options for some of the commands I'm using. (I needed to look through the syntax for this effort, and I learned something...so I save it for a future effort!) When I'm done, and I've figured out the proper sequence of commands, I now have a basic document that shows me the correct steps, and a few added notes for related commands. If I take an extra 30-60 mintes, I can add some comments for the next time... things to be aware of, pitfalls to avoid, information to gather before you start, how long it might take... these all get into the document.

At the end of the effort, I now save a copy of the file in a "Clues" directory. This is my 'canonical' place for the most current version of my clues, for anything I've worked on. I've written my stories down, and everyone on the team knows where to look for them if they need to work on a project. If I'm unavailable, my team will still have access to useful knowledge on an array of tasks. (And, if it's easy to hand off a project, it's more likely I'll be able to hand it off and do something more interesting the next time.)

Make a clues repository, start gathering simple process docs, and get the other folks in your department to share in filling the repository.

-Z-

No comments: