Best Practices for Documenting Technical Procedures

Documention Your Technical Roadmap

Documentation – Your Technical Road Map

Documentation isn’t something most of us enjoy, but in reality it is essential to what we as DBAs do.  Now, I’m not talking about Oracle documentation here, we all read plenty of that.  The documentation I’m writing about pertains more to compiling your own notes for specific tasks. I’ve been accused of over-documenting at times, but I’ve found that a little extra documentation in the beginning can actually save a lot of time in the end.

Take for example, a situation where you need to perform a task you don’t do very often.  Oracle provides an abundance of documentation to read, but usually your task will only pertain to a few small sections of the lengthy documents. Copy these sections into your own document and organize them into step for completing your task. To make life easier, you can include screenshots of any specific commands you’ll be using.

Once the list of steps is finished, add the specific commands you’ll need for each step, and then take it to the sandbox for testing.  When testing is completed, you’re ready to tackle your task.

As an example, I’ve included my process for documenting the simple, yet important, task of manually switching over databases in a Data Guard environment:

Perform Data Guard Switch-Over

1. Shutdown applications and all user connections to primary

Log on to primary and verify user processes:

  • set lines 200;
  • set pages 9999;
  • col osuser format a20;
  • col username format a15;
  • col machine format a30;
  • col program format a40;
  • SQL> select sid, serial#, process, program, osuser, username from v$session where type = ‘USER’ order by osuser;
  • SQL> alter system kill session ‘,<SERIAL#>’;

2. Verify archivelogs have all been shipped and applied on the standby

  • set lines 200;
  • set pages 9999;
  • SQL> select sequence#, applied, to_char(FIRST_TIME, ‘MM-DD-YYYY HH24:MI:SS’) from v$archived_log order by sequence#;=

3. Connect to DGMGRL and perform the switch

Check the status of primary and standby

  • DGMGRL> show database PROD1; # Showing primary role
  • DGMGRL> show database PROD2; # Showing standby role
  • DGMGRL> switchover to PROD2;
  • Performing switchover NOW, please wait…
  • Switchover succeeded, new primary is “PROD2”

Verify Roles have been switched:

  • DGMGRL> show database PROD2; # Showing primary role
  • DGMGRL> show database PROD1; # Showing standby role

4. Review alert logs to verify there are no problems, and see that log ship and apply are working.

5. Restart applications (connecting to the new primary PROD2).

6. Copy-paste the entire output and save it as a new document in a separate folder relating to the task, in case there are questions later.

Once you are finished, you will have 2 documents. One is a master document you can file away in your document library, and the other is the screen output showing the individual steps performed for the specific client or job.

As you can see, a little extra documentation in the beginning can save you time and a lot more.

  • Saves time: Everything you need to do will be listed for you in order.  You can copy/paste from your notes.
  • Reduces errors:  No fumbling for exact syntax, or forgetting to do something (No blind typing at 2 am.)
  • Consistent steps provide a consistent outcome
  • If you or any of your team need to do the same task, it’s easy to share notes.
  • Documented steps and output if there are questions later.

This was a simple example, but hopefully you can see the benefit of this level of documentation for many of the tasks we as DBAs need to do.  Things like installing a new product, doing a task you have never done, or even doing a series of familiar tasks in a tight maintenance window, will be all accomplished more efficiently, and with documented results.

About the author

Rick BrownRick Brown, Senior DBA

Rick Brown brings over 10 years of Oracle database experience to the tech team here at Guardian Eagle. Rick started with Eagle as an Oracle DBA in 2005 and now provides specialized database support and services to our clients as a Senior Oracle DBA. Rick is distinguished as an Oracle Certified Professional DBA with Administrator Certifications in Oracle Database 8i, 9i, and 11g.