Last week at work we had to demonstrate in a proof of concept single signon integration with Netegrity's product SiteMinder. As usual this involved us in installing, configuration and interfacing to software we'd never worked with before. When this happens we have to rely on the manuals.

The problem in this situation is that the manuals are not designed around the task we're trying to complete. Instead of a detailed and thorough explanation of all the possible options and the way to select the correct one in each situation, which is what a manual should provide for more normal uses, what we need is an explanation of how to get something up and running quickly in a simple situation. There's just not enough time, unfortunately, to understand everything in detail. We need a good conceptual model for the software and how-to style configuration information for the simplest possible working setup.

I imagine the actual readership for such a thing would be fairly limited for most software. For something like, for example, SiteMinder or a Portal product though, there must be a fair number of people who have to perform integration as third parties, not just install or setup for end users.

We did get it all working in the end though. Turned out to be pretty easy really, at least for the simple configuration I went with. Fortunately the design of our security system just required adding an addition SiteMinder specific module and modifying the configuration files. The whole thing could be shipped as a drop-in jar file.