copy and paste does not good documentation make.

I have had 2 presentations accepted for the UKOUG conference 2007. It's probably not a surprise that one of the subjects I will be covering is the application of Critical Patch Updates to an oracle E-Business Suite installation. The presentation will be largely based upon our experiences and the documentation that I always make sure comes out of a new exercise.

A little background first. Our development environment, which I inherited consists of two database nodes and two application tier nodes. There are in total 8 environments running here. The EBusiness suite database is installed using ASM for storage on Red Hat linux.  Each environment is owned by a unique oracle software owner. In addition on the apps tier each environment is owned by it's own applmgr account. Finally on the database nodes the clusterware and the ASM instances are owned by a dedicated Oracle clusterware owner.

I therefore wrote a patch application procedure which included the steps we needed to take to upgrade in our environment, based on the readme for patch 5901877.  For a RAC environment the readme states.

 

3.3.4 Patch Installation Instructions for a RAC Environment

Follow these steps:

1. Shut down the instance on one node.

2. Shut down all nodeapps services on the node in step 1:

   srvctl stop nodeapps -n <node-name>

 

Now I am not, at this stage, patching the Clusterware, so I removed the nodeapps description and consequently my procedure read.

1. Shut down the instance on one node

srvctl stop nodeapps -n <node-name>

Imagine the surprise when my colleagues reran the procedure, to verify the documentation and one by one all 8 environments started shutting down, though I think it was only when ASM went down that they considered that perhaps something a little untoward had occurred. There are some useful lessons that might be drawn from this.

First as the title suggests cut-and-paste isn't necessarily a great means for generating documentation - especially if you plan to only take relevant parts of a multi-purpose document.

Second, it nearly always makes sense for someone who didn't write the procedure to follow it to see if it actually works.

Third, it makes sense to test procedures in a test environment after having written them. This is a different form of testing to actually testing the effect of the procedure.