Manageability, Maintainability, and Supportability
Updated December 2007
Summary: Software configuration can ease the pain—or be a source of it. (5 printed pages)
Singing the Configuration Blues
How many times in the past has a small change in requirements necessitated a change in code in a part of the system? Instead of a simple change to a setting, it required a change request, scheduling development time, modifying code, testing, and redeploying the software.
Not this time. The software for the new system being developed is going to be highly configurable. The development guidelines are very clear. Anything that could possibly have to be changed must have an associated setting in a configuration resource. It will be a simple matter to maintain the system. A server has become overloaded? No problem. A component of the system can be moved over to another server. A change to a setting here, a change there, and the system keeps on keeping on.
The time has arrived. Each component of the system has been fully tested and is ready to go. Integration-testing is set to proceed. The quality-assurance specialists install the various components and start the system. Hmm, a part of the system failed to start. It turns out that there is a configuration resource missing. After tracking down and installing the missing resource, it is time to give it another try.
The system fails to start again—another error that is related to configuration. This time, the offending resource is present, but it is not located where the component expects it. Okay, that is fixed. It's time to try again.
Ugh. The system still won't start properly. There seems to be a port conflict between components. It turns out that multiple components are getting their information from the same section in a shared configuration resource. After straightening out the mess, it is time to give it yet another try.
Hmm, now one of the components is complaining about missing configuration values. Wow, there are a lot of things that must be configured for this component, and the documentation is not providing much help. After a long consultation with the development team, some appropriate values finally are obtained.
Great, the system is now up and running. Upon executing one of the tests, however, errors start showing up in the event log. After a lengthy debug session, the source of the problem is discovered. It cannot be, but it is: yet another configuration problem. A value was set too low.
After increasing the configured value, the test is run again. More problems: It turns out that you cannot just increase the value of that parameter. Two other configured values also must be adjusted. Hopefully, the settings are now in harmony with each other.
After running more tests, another problem rears its ugly head. A further configuration parameter must be adjusted. The problem is that the parameter applies to a component that is installed on multiple computers, each with its own configuration resource. So, the change must happen in multiple places.
This is frustrating and downright annoying! Actually, it is more than annoying; it's embarrassing. Instead of an easily maintainable system, it has turned out to be a configuration nightmare.
Singing the Configuration Blues
What to do, now? Obviously, the configuration of this system is way too complex. There are too many configuration resources, and they exist in too many different locations. There are too many things to configure, and the documentation fails to provide enough help to determine the proper values.
Did this really happen? Well, yes and no. The events as told in this story did not all happen on one project. However, I have been involved in projects with some of these issues and have observed the other types of configuration issues on other projects. As outlined in this story, when done poorly, component, application, or system configuration can be a source of grief instead of a source of relief (at being able to resolve an issue with a simple setting change). Instead of the smooth sailing that you envisioned, you end up in dry dock singing the configuration blues.
The concept of configurability reminds me of my days as a boy building models. Models that provided choices were more fun and satisfying to build. For car models, you could choose to build the engine in different ways, choose different lights, choose different spoilers, and so on. Of course, the more choices that were provided, the more chances there were of putting things together incorrectly (especially if you did not read the instructions) and having parts left over that were not just the parts for configurations that you did not build. Fortunately, the models only had to sit there and look good; they did not have to run. This is not the case with software systems.
Configurability is like any other part of a software system. It's not enough just to make things configurable. To be effective, the configurability of the software system as a whole must be considered and designed up front carefully. As an old commercial for changing the oil filter in your car said, "Pay me now or pay me later, but you'll pay a lot more later" (or something to that effect).
Five Ws and an H
One reason for ending up in configuration hell is limiting design to answering only the question "What?" as in, "What has to be configurable?" Asking and answering other questions of "Where should the item be configured?" or "When and/or why should the item be configured?" and "How should the item be configured?" are pertinent to making configurability a positive quality for a software system.
Of course, the "What?" question does have to be asked. In determining what must be configurable, ask whether the ability to configure the item outweighs the negative impact on the software system if the item is configured incorrectly. Just because something can be configured does not mean that it should be.
While answering the question "Where?", keep in mind that it is usually better to have fewer configuration resources than more. Components that execute within an application should get their configuration information from a section within the application's configuration resource, instead of from their own configuration resource. Good development platforms provide the necessary framework and libraries to make this easy to accomplish. For distributed software systems, it is best to obtain global configuration settings from a central resource, making the system easier to maintain. When the system is database-centric, this is usually done through the use of configuration tables within the database. Applications that must run when disconnected from the central resource can cache the settings locally for use only when disconnected.
Why and When
Answering the questions "Why?" and "When?" helps determine which configuration items are mandatory and which items are optional. For example, an item might have to be configured only if the performance of the system must be tuned. In this case, configuring this item should be optional. The item should not have to be specified in the configuration resource. Instead, the software should provide a viable default value that is used when the item is not defined in the configuration resource. Of course, when the item is specified in the configuration resource, it overrides the default value. Following this strategy allows the system to be highly configurable, while at the same time making it easier to get up and running.
When referring to the question "How?", I think of it in the context of the person having to set the configuration values. How do I choose what value to enter? What are the ramifications if I choose one value over another? In what situations should I choose this value or that value? Surprisingly, it is more often the case than not that little help is provided in answering these questions. The documentation just states to choose or enter a value in this field. This often leads to much pain later when it's found that the value that was entered was not appropriate for this installation. Remember to provide enough information to allow the person setting up or maintaining the system to determine the correct value to use for a configurable setting. Providing help within the configuration resource itself also is often a good idea, as separate documentation is sometimes hard to locate after a period of time.
In the cases in which the settings of certain items are affected by the setting of another item, ensure that the relationship is evident in the configuration resource. For example, make the dependent items sub-items of the independent item, and be sure to document how the items relate. If possible, have the software override incorrect dependent settings with applicable defaults, and issue a warning instead of failing with an error.
The strategy of simplification applies also to configuration-management tools. The temptation seems to be to place as many of the configuration items on a single page as possible. This is very daunting to the person who is trying to configure the software. Even when the configuration items are spread over multiple tabs, it still can be intimidating. Instead, show only the mandatory items on the main page or tabs, and hide the optional items behind links or buttons with captions such as "Advanced Settings."
As our title suggests, one of the goals of configurability is to improve the maintainability and supportability of a software application or system. With the proper tools, manageability also can be improved. Maintainability has been defined as "the ease with which a software system or component can be modified to correct faults, improve performance, or other attributes, or adapt to a changed environment" [IEEE 1990]. The keyword here is ease.
· Do the benefits of making an item configurable outweigh the downsides of making it configurable?
· Where should the item be configured? Is it local to an application or global to the system?
· Why and when should the item be configured? Is it mandatory or optional?
· How is the value for the configuration item determined? Is enough information provided for a person to configure the item correctly?
· [IEEE 1990] IEEE Standard Computer Dictionary: A Compilation of IEEE Standard Computer Glossaries. New York, NY: Institute of Electrical and Electronics Engineers, 1990.
Maintainability—"The ease with which a software system or component can be modified to correct faults, improve performance, or other attributes, or adapt to a changed environment" [IEEE 1990].
Manageability—How efficiently and easily a software system can be monitored and maintained to keep the system performing, secure, and running smoothly.
Supportability—How effectively a software system or component can be kept running after deployment, based on resources that include quality documentation, diagnostic information, and both knowledgeable and available technical staff.
About the author
Terry Young has worked in the software-development field for over 25 years. He currently lives in Kitchener, Ontario, Canada and works as a software architect with a talented group of people at PEER Group, a company developing custom software solutions and products for the high-tech manufacturing industry.
This article was published in Skyscrapr, an online resource provided by Microsoft. To learn more about architecture and the architectural perspective, please visit skyscrapr.net.