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:
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.