What to do when there's nothing to do?

I'm in one of this situations where the product is in Beta, stable but not yet actually released. Therefore the codebase is locked down such that only the most pressing code changes are allowed to get checked in. In the ideal situation we'd have a branch of the code and a set of tasks to work on for the *next* release. For various reasons we don't have that at the moment. So.. it means unless a critical bug comes in in my code, then I'm locked out from doing any coding work at the moment.

 *twiddle thumbs*

Here's my recommendation on what to do in this situation: Document!

I know most programmers hate writing any sort of documentation, but someone working on installers and configuration management tasks is dealing with an area that even more urgently requires documentation. Most sorts of code you can write comments into it to give some explanation of why it is done that way. Some new programmer walking in off the street has a reasonable opportunity to grasp the basic flow and policies that went into how the code works.

Because MSI installers are table-driven, there isn't any good way to comment like this. Not only does a new install developer have to fumble around blindly, but I even forget why I did things the way I did if I'm away from the installer for a couple months.

The solution here is to document, at least in a basic form, the thinking behind why the install does what it does. I do this by making the document feature-based. For example, I have a feature where I want to validate the path a user has entered on a dialog. In order to support this feature there are entries in about 5 different tables (ControlEvent, Property, CustomAction, AppSearch, Etc.)

In my document I make a heading for this feature, explain what the feature is supposed to accomplish (in plain English), then list the 5 table entries that are required to provide this feature and explain in simple english how those entries relate to each other. For most features this takes a small paragraph and a 4 to 8 item bulleted list. Simple. I keep the document going, adding features to it as I add them into the installer. I guess you might call this a technical spec - I don't know the official term for it. I also go ahead and check this document into source control right alongside the installer project so that the two are easily located together.

A great benefit of writing this kind of documentation is that if you ever need to add this feature to another installer, you already have the pattern for how to do it. Similarly, if you ever need to remove that feature, you know all the little pieces that go with it and can remove it cleanly.

This is the type of documentation that often gets left out, but can really make a difference in providing long-term quality of code. Also, managers love it!

Hope you are enjoying living the Lifestyle of the MSIdle!

Susan

Published Tuesday, July 01, 2008 9:25 AM by SusanGorman

Comments

# re: What to do when there's nothing to do?

Wednesday, July 02, 2008 10:27 AM by HookEm

And if you want your MSI package to meet the MS Windows Logo Certification requirements then you know it's a requirement to provide system administrators with documentation explaining what each custom action in your MSI package does (except for type 19, 35, and 50 CAs).

If you use InstallShield to generate your package, they would have you create a separate text file for each CA.  I hate that approach.  I'd rather see all the CAs described in one document so I created an RTF file with a table for each CA that not only describes what each CA does, but also lists the type (broken down into the individual attribute flags such as "1+256+1024") and where it is sequenced in each of the sequence tables.

In addition, so as not to confuse the typical user who probably doesn't know anything about CAs or care what they are doing, I added a UI dialog to the Admin UI sequence that displays the RTF (similar to an EULA dialog) and allows the user running an administrative install in full UI mode to print the RTF.

# re: What to do when there's nothing to do?

Wednesday, July 02, 2008 1:45 PM by SusanGorman

I love the idea of a single doc for the CAs as well as putting that doc in the Admin UI sequence. Good plan!

# re: What to do when there's nothing to do?

Friday, August 08, 2008 5:42 PM by Airborne Bodhi

Hi Greg,

I look around the Internet to find old friends

as the world "gets smaller" on a daily basis.

This then brings me to the question: are you

The Greg David Gorman that at one time attended

SJV? It would be great to re-connect with you

if that is the case.

Your Old Pal,

Tommy Ward