I have found that performing software configuration management tasks requires many specific skills that don't get used on a consistent basis.  You might spend several days writing build scripts using UNIX scripting language and end up not using that language again for several months.  Meanwhile, you've been writing procedure documents and developing customized reports using a database query tool.  In the middle of that task, one of the developers can't access the code they need from the version control tool and you spend a whole day troubleshooting that problem.  A year later, the problem reappears on a new client machine.  How did you solve it last time?  I don't know about you, but I'm lucky if I can remember what I packed in my lunch this morning let alone how I solved a specific problem twelve months ago.  What can you do to remember it all? Get a new brain?

A brain transplant might help you increase your memory capacity and overcome all the damage from the abuses of your undergrad years, but let's face it, medical technology isn't quite there yet.  The solution to this problem is to simply write stuff down.  This obviously isn't rocket science and isn't the newest idea on the block, so why aren't you doing it?  Maybe you tried to do it or you are doing it but your method isn't very well organized or useful.  Most of us intend to write things down but run out of time, or if we did record a solution, it can't be located when it is needed, especially in a high-pressure situation.  All you need to do is develop some good habits and have a system that's easy to use and maintain.

First you need to develop a simple system for storing information.   There are a lot of fancy-schmancy ways to do this.   I'm sure many of you detail-oriented configuration management professionals out there would love to develop a complex, relational database with tons of different fields that could be queried to locate the minutia of every event detail (indeed, some of you probably already have).  Hey, if you have the time and energy to do this and you will actually use it, go crazy!  Most of us, however, don't have the luxury of the time this would take, so a faster solution is needed.  You need something that is simple, portable, easy to update and maintain, and doesn't require a huge learning curve.

To illustrate my point, I will explain the system I use.  It's a method that may or may not work for you, but it could be something you could start with and certainly customize and improve for your own situation and tastes.  I personally use a word processor program and the window's file system - that's it.  This ensures that just about anyone can use the information, and it can easily be accessed on most modern PCs.  Outside of the word processor, no special software is required.  I simply call my "database" an event log, and each event is logged in a separate document.  I prefer to capture things electronically because it's hard to find information in a stack of old notebooks and papers.  My handwriting has also deteriorated to the point where it can only be deciphered by highly paid cryptographers.

I use a document template I created that has a header section I fill out with some basic information for each event, like a title of the event and the date it occurred.  You could certainly add other information to your template to make it easier to use, but remember to keep it simple.  Once you start actually creating logs, you might get different ideas how to model your template for easier usage.  Try different things out, but keep it simple and get rid of things you don't use. 

I store my event logs in a directory called, you guessed it, "Event Logs"!  This is then broken down into subdirectories by year.  I actually have different event logs for different high level categories, like a log for Tool A, one for Tool B, and one for general SCM.  You can organize this any number of ways, but a single even log is a good way to start.  I name each document based on the date, then I add a number to the name to make it unique if there is more than one log generated on the same day.  For example, a log file could be named...

"Event Logs\2003\CM_Log_120903_01.doc"

Which is the name of the first log file generated on December 9, 2003.  I use leading zeros when necessary for sorting purposes (e.g., I use "01" for the file number to allow the proper sorting of up to 99 documents for one day).  Directly under the Event Log directory, I also maintain a single file called something like CM_ TOC.doc (for Table of Contents).  I update this file with just the description title of the log in a column on the left, and the file name of the log on the right, just like any garden-variety table of contents.  That's my database.

There are many different ways this can be done, and this one just happens to work for me.  You could put the event description in the file name, but this restricts how descriptive you can get and makes it difficult to organize using subdirectories.  Besides, who likes sentence long file names?  Using dates as file names keeps things neat and easy to locate.  Sorting by file creation or modify date can make it difficult if you create things out of order, but sorting on the file name based on a date is a breeze.  It also makes it easy to "insert" a log that might have occurred before other logs were created but did not get written up on time.  You also don't have to worry about making up unique file names.

Now that your log system is created, how do you find information?  For my system, I first open up the Table of Contents document and use the Find command to locate any key words that might exist in the summary descriptions I entered here.  You should keep searching in mind when you created the summary descriptions.  If you did a good job at that, it should be easy to locate the log file you need in the table of contents.  Once you find the description, the corresponding log file is easy to locate because it's based on the date.  You just locate the proper subdirectory for the year, and all the files are in order by date.

What if you can't find what you are looking for in the table of contents file?  Then you search through the contents of all event log files. To do this...

• Right click on the Event Log directory in Window's Explorer and choose Search (which will limit the search to just the Event Log and it's subdirectories).
• Enter search criteria for text that exists inside the files and search for a key word or phrase you know is unique to the log you seek. For earlier versions of windows such as the Win9x series and NT 4, the search command is called Find, and you use the field "containing text" to search the content of the files.
• The results then list any files that match your query, and you can open them directly in the results window to see if they are the files you were looking for.

The Difference Between Important and Urgent

Have you ever taken one of those time management courses or read a book where they teach you the difference between important and urgent?  Many people mistake urgent tasks for important ones, and important tasks that aren't urgent get ignored.  This activity qualifies as one of those important, non-urgent tasks.  It's not going to jump up and hit you over the head to be created, and the boss wont' be looking for it, so you need to take the initiative to do it yourself.

Once you have created your system, you just need to develop the discipline to use it! For me, this means recording events as they happen.  If you get distracted from your work to solve a problem, your natural inclination is to dive right back into whatever you were doing before Henny Penny ran into your cube to tell you the sky was falling.  As soon as you resolve any issue is the moment you need to record what happened.  You need to do this when it is fresh in your mind.  The longer you wait, the more likely it won't get done.  At the very minimum-make sure you update it before you go home at night.  If you wait until the next day, Seinfeld re-runs, the kid's homework, surfing the Internet, etc., will replace all that information in your head and you won't have a clue what happened the day before.

So far I have suggested you record how you solved certain problems so you can re-use that information if needed.  This comes in very handy for specific technical issues that contain a lot of details (like the exact syntax of a command you used).  Recording these types of events will probably have the greatest benefit for your individual work.

There are certainly many other things that you could and should record as a CM professional.  In his book Introduction to the Personal Software Process by Watts Humphrey, the author describes creating an engineering notebook to keep a log of events as a fundamental part of good software development.  In your general or project specific event logs, you could record such information as when certain changes took place (e.g., when the build environment changed), who made the changes, and why they were made.  These types of logs can assist greatly for general status accounting and during audits and reviews.  It can also come in handy if you are every asked the famous management question, "What have you been doing with your time?"  If you've kept an accurate log of your activities, you have an instant answer that's difficult to dispute.

You can save time by capturing information as it happens which will make is much easier to create the log when you are done.   Information such as error messages and command line output can be quickly copied into a blank document with a few notes here and there so you can organize it later into the official log file.  This is especially handy if you are working on another user's machine.  You can just email yourself the file you created to get the information back to your own PC for the formal write up.  In the following paragraphs I have included a few tips and techniques I use to capture and record the information as it happens.

Capturing images from the screen is a great documentation method.  This technique is also very handy for writing procedure documents.

• In Windows, you can capture the active window on the screen and paste it to the clipboard pressing the [Alt] and [Print Screen] keys simultaneously.
• If want to capture the entire screen, press [Ctrl] and [Print Screen].
• Once the image is on the clipboard, you can further edit it if needed by opening up a simple image editor like Paint and pasting it into a new file. Then use the crop tool to hack out things you don't need. You can save the result as a bitmap file, or copy and paste it into your word processing document.

Capturing Command Line Output

From a Windows command prompt (DOS), you can capture output by redirecting it to a file using the redirect symbol.

• After a command, use ">" to create a new file or overwrite it, or ">>" to append to an existing file, followed by any file name (e.g. "batch.bat > log.txt"). This works for UNIX too, of course, but you knew that already.
• If you want to capture the output or text that's already on the screen of a DOS window, click on the command window icon in the upper left corner of the window to access a drop down menu.
• Choose "Edit", then "Mark".
• Use your mouse and click the left button to highlight the text you would like to copy, and then hit the [Enter] key to capture the highlighted text. This copies the text to the clipboard and you can then paste it into your document.

Short Cut for Migrating to Directories from the Command Line 

While on the subject of DOS command lines, following is a tip to avoid having to type out a full path name to get to a deeply buried directory from a command prompt.

• Open a command prompt window and change to the drive letter of the drive where the path you need is located.
• From Windows Explorer, open the directory you need to get to.
• Select a file in this location (any file will do), and drag and drop it into the command window. The entire path name will show up in the window, including the drive letter.
• Use the backspace key to delete the file name from the end of the path, and then hit the [Home] key to get to the beginning of the line.
• Type ‘cd' followed by a space, which should overwrite the drive letter, the colon and slash (if your typing inserts instead of overwrites, it will still work), then hit [Enter].
• Voila! Your cursor is now located in the directory you wanted, and you didn't have to type much of anything.

Avoid Grammar and Spell Check on "Non-Language" Text

If you have spelling and grammar checking turned on in your word processor, it can be very hard to read command line information and output that you paste into your document because so much of it is not normal language.  To correct this, create a format style for "copied text" that is has the spelling and grammar checking turned off.  When it is applied, the text in this format is left unmolested by those relentless red and green squiggles, but the rest of the document can still utilize the spelling and grammar features.  You can also add other attributes to this format style that distinguishes it from the rest of the text, such as a different font type and color.

You can use many other methods at your disposal to gather information, like the UNIX "script" command that captures all activity in a file until you turn the command off.  If you have your own tips on simple data gathering, start a discussion thread under General CM Forum and share them!

Now that you are all fired up about creating event logs, you can also use this technique at home.  For example, this year I recorded exactly how I strung up all my Christmas lights on the house.  When the holidays roll around next year, I can spend more time inside drinking eggnog and less time outside in the freezing cold fumbling around like Clark Griswold.  Happy Holidays!

Trackback(0)

TrackBack URI for this entry

Comments (0)

Subscribe to this comment's feed

Write comment