Setting the Right Value

In discussions regarding configuration parameters, the tarchitect and marketect must together meet both the needs of the user affected by the parameter and the needs of the user (or system) setting it.

In general, most users are not aware of the full range of configuration parameters that exist for their application. They don't need to be. In writing this chapter I did a quick search on my computer for all files with the extension .ini (I'm writing this book on my trusty laptop running Windows 2000). I had expected to find two to three dozen , so imagine my surprise when I found more than two hundred! A cursory review revealed that most of them weren't really storing configuration parameters of the kind I'm talking about in this chapter but instead were using the Windows facilities as simple persistent storage.

However, some, were clearly configuration files as defined in this chapter, with various settings based on user needs. In considering those needs here, remember that increasing the number of configuration parameters increases the likelihood that they may be set to improper or useless values and generally detracts from usability because of increased complexity.

The previous sections provided the information you need to give to the entities setting the values. Simply put, they need to know what values to set, how to set them (including formatting and valid values), why to set them, and their effect on system operation. Give this information in the file, not in some external document or hidden on a Web site. Let the entity using the file understand what is happening.

The caps.ini file, distributed as part of the Microsoft Platform SDK provides almost all of the answers that a user needs to modify these values. Here is an extract under the section [CAPS FLAGS] . The file could be substantially improved by adding some information about the effect of setting each of these parameters on or off.

 [CAP FLAGS]  # CAP accepts the following parameters: #    *  profile        = (on/off) #    *  dumpbinary     = (on/off) #    *  capthread      = (on/off) #    *  loadlibrary    = (on/off) #    *  setjump        = (on/off) #    *  undecoratename = (on/off) #    *  excelaware     = (on/off) #    *  regulardump    = (on/off) #    *  chronocollect  = (on/off) #    *  chronodump     = (on/off) #    *  slowsymbols    = (on/off) # # Anything value other than on or off is encountered # and the default values will kick in: #               profile        = on #               dumpbinary     = off #               capthread      = on #               setjump        = off #               loadlibrary    = off #               undecoratename = off #               excelaware     = off #               regulardump    = on #               chronocollect  = off #               chronodump     = off #               slowsymbols    = on # # Please notice there are no spaces between the keyword # and the value (either 'off' or 'on') # 

While the instructions provided in this document are clear (at least to me), they do contain some minor grammatical mistakes. Because such mistakes will happen, involve your technical publications department in preparing configuration file documentation (including its internal documentation). They shouldn't write the initial description of these parametersthat's the job of individual developers as reviewed by the tarchitect. However, they should be involved in the final review process because they know how to structure and communicate important information.