It Configures
Some weeks ago, I rambled on for a while about making a use case for scenarios. It came about through an experience working on a project where a specific set of features of the software were so complex and unintuitive when you randomly played with them that it seemed almost impossible to provide potential users with any useful guidance on what they were actually there for. I can now reveal that the software in question was the new configuration tool for version 5.0 of Enterprise Library.
I have to grudgingly admit that the new configuration tools are extremely good. Yes, I was doubtful when I saw early versions, but now they've tidied them up and made them do useful things, I really do like them. Even if they are almost impossible to successfully "screenshot" for documentation purposes due to the vast amount of horizontal screen width they absorb. Maybe we'll be OK when they invent books with pages that scroll sideways (or everyone starts using e-readers).
The bits that we (the doc and test teams) struggled with are the advanced configuration options that allow you to generate and consume configuration settings other than all in a single Web.config or App.config file. For some time, because it uses pluggable configuration source providers, Enterprise Library has supported configuration from a database (using a separate sample provider) and configuration that honors Group Policy settings. It's also been possible in the past to generate different run time configurations for different deployment environments, which is useful when the requirements for dev, test, and production systems differ.
However, in the new version you can use shared and inherited configuration settings. The problem was that the features to enable this were called "hierarchical configuration", "redirected sections", and "rules for configuration merge". We all believed that they only made sense to the developer who created them, and were - to say the least - surprised when even he admitted that he was struggling to identify the scenarios for their use. It's no wonder that we doc and test people were breeding whole new migraines every week.
What we had ended up with in the docs up to this point was accurate documentation of each feature, together with detailed instructions of how to do it and examples of the resulting XML configuration content. But there was no way you could decide which of the multiple options you needed in order to perform some specific and obvious task, and you ended up being sidetracked by details of how they worked - basically because, by simply playing with them, that's all you could figure out.
And, of course, the usual documentation nightmare occurs in this situation. As each technical reviewer tries to make sense of it, they add a plethora of comments and suggestions, complete with notes about "things you should tell users" and "important points when using the feature". The result is, not unexpectedly, a guidance document that is basically just a series of notes interspersed with code samples as you try to satisfy all of the requests and feedback. By the time you are done, the content generally makes even less sense, and is even more unusable. All because you didn't (or couldn't) identify at the beginning exactly what the user would want to do.
But finally, after a long and productive teleconference and consultation with our product manager, we nailed down the scenarios for all this. And, when you see them, it all instantly makes sense:
Using a Non-default Configuration Store. In this scenario, you want to store your configuration in a file or other type of store, instead of in the application's App.config or Web.config file. You can use a different file that follows the standard .NET configuration format, use the example SQL Configuration Source available from the Enterprise Library Contrib Web site to load configuration information from a database, or create a custom configuration source.
Sharing the Same Configuration between Multiple Applications. In this scenario, you want to share configuration settings between multiple applications or application layers that run in different locations, such as on different computers. You simply implement the same configuration as described in the previous scenario, locating the configuration file or store in a central location.
Managing and Enforcing Configuration for Multiple Applications. In this scenario, you not only want to share configuration settings between multiple applications or application layers that run on different computers (as in the previous scenario), but also be able to manage and enforce these configuration settings for this application or its layers on all machines within the same Active Directory domain. You use the configuration tools to generate Group Policy templates and a Manageable Configuration Source to read your configuration information from a local or a shared configuration file.
Sharing Configuration Sections across Multiple Applications. In this scenario, you have multiple applications or application layers that must use the same shared configuration for some application blocks. You redirect Enterprise Library to use some shared configuration sections, rather than using a complete shared configuration, and local settings for redirected sections are ignored.
Applying a Common Configuration Structure for Applications. In this scenario you have a number of applications or application layers that use the same configuration structure and you want to inherit that structure but be able to modify or add individual configuration settings by defining them in your local configuration file. You specify a configuration that inherits settings from a parent configuration source in a shared location, and optionally define local settings that override inherited shared settings.
Managing Configuration in Different Deployment Environments. In this scenario, you want to be able to define different configuration settings for the same application that will be appropriate when it is deployed to different environments, such as a development and a test environment. You use environmental overrides for settings that are different in two or more environments, and the differences are saved as separate delta configuration files that the administrator then merges when the application is deployed in each environment.
So, tying each feature to a scenario was the missing link. It meant that I could present a list of "What do you want to do?" options, together with an explanatory schematic for each, and then detail the steps for each scenario separately. And, as most of this was already written, the task was not as time consuming as it had seemed at first. It's amazing what a difference it makes writing guidance for software when you understand what it's supposed to do, rather than having to discover what it does and then try and figure out why it does it...
And if you decide to play with the software yourself, I'd be really happy to hear if you agree that we finally did nail it. You can get it all from here.