You are currently on IBM Systems Media’s archival website. Click here to view our new website.

Bookmark and Share

Recent Posts

Documentation Worth the Effort

April 27, 2009

I like to eat. That's a good thing too, since going too long without eating will kill you. Of course, eating too much and/or exercising too little isn't a healthy way to live.

Hopefully we're making better choices these days about what and where we eat. Making meals at home instead of eating out is a good place to start. Of course, a home-cooked meal requires preparation. Perhaps you need to reference a cookbook or dig up an old recipe so you can remember the correct measurements for the different ingredients.

Building a server has its parallels to making a meal. Just as recipes and cookbooks are essential to food preparation, we in IT rely on documentation to properly build a server. As an old coworker would point out, how will we know what's in our "golden image" unless document all of the software that we've loaded? How will we track the special requests that come in during the build process if we don't make note of them?

Some argue that the system documents itself. If you want to know what's loaded, you can find out by logging on and running various commands. That might work under normal circumstances, but what if the server dies and you need to rebuild it? Referencing the information that's on the dead machine might be a challenge then.

Others prefer automated tools (e.g., this and this), or even address their documentation needs with the IBM System Planning Tool.

These tools certainly can be useful, but again, think big picture here. Sure, when it comes to your environment, you can probably create a file system in your sleep. But when a newly promoted junior admin joins the team, can you point the newcomer to the instructions that specify how you want it done? How will new admins learn without carefully compiled documentation?

All environments have unique requirements. One organization might prefer that CIO mount options are used for particular file systems. Another may want raw logical volumes, or have some other requirement when the server gets built. Isn't it important to have server build standards that you can compare to these requests?

While it's true that putting out fires takes priority over washing the walls, those walls still need to be cleaned.

Documentation and server build standards are critical. It's one more thing that we must be sure we make time for.

Posted April 27, 2009| Permalink