That's always been the problem, and as you noted, the IdP docs aren't precisely task-based, it's just that the organization of the configuration is more task-centric.

I would focus for now on just getting the content in.

I may recast the "top level" of the current SP documentation when I start up in there again later today to be more task driven.  Or not.  What I'm not sure about is the slight impedance mismatch between the Element {{<MetadataProvider>}} and the task "adding Metadata" (plus an aside that I'm not 100% positive right now that the {{<ApplicationDefaults>}} is the only place it can go.  Maybe I should leave as is right now and concentrate of adding content (MetadataFilter is what is next, then I'll move on to whateveer documentational infrastrcture is needed to support the IIS7 changes.

I think you've hit on the problem, and in a nutshell I don't know if it will work or not, but I think it would be a great improvement (IMHO). But I know there are people who probably would argue one file is better, particularly when it's already fairly short (in comparison to what it used to be).

One problem is that most of the plugin config is application-centric, not SP-centric. So mostly this is probably about breaking up the config such that applications are defined in separate files, and I'm not sure that would be a benefit or not. Perhaps.

More generally, I was asked to figure out a way to support "includes" a long time ago, and at the time I only considered trying to do that with the XML Include standard, which Xerces didn't support. It also is a terrible standard, as it turns out.

The XMLServiceProvider class is absolutely horrible, it's a single giant mass of code to load the entire configuration tree, exactly the sort of thing that led people to figure out Spring was a good thing, but this isn't Java, so it's not as easy to fix.

What I would say for the moment is that you're right that it won't be as elegant, but at least breaking the topics up by functional area and then having those topics explain where in the file you would put something would still be better than it is now.

We discussed this and SP3 documentation briefly in the team meeting on Friday the 19th.

One of the things that said was that he wanted to structure the SP3 documentation to be more like the IdP documentation which is to say task driven rather than file driven.  This surprised me since I had always considered the IdP documentation as being file driven, not task driven.

Last night I had an insight which squares this circle. 

It appears to me than in fact it is the layout of the files in the config file which is task driven.  The documentation follows this and hence it too is task driven.  I find that a very natural way to proceed - particular as a beginner I had to hunt for the correct place to add metadata or to resolve attributes and so on.

As a corollary, one of the issue I have in trying to document the MetadataProviders for V3 is the depth of psuedo stru cture needed before I can get to the metadata providers - and hence why Scott wants to structure the documentation by task/function.

I wonder whether we could do the same for the SP.  I have still to dive down into the fullest corners of the SP configuration but could we not split top level functions into files (Metadata provision, Handlers, Attributes, ShibD config, WebServer config, ...) and refer to these files with attributes inside the <SPConfig/> element?  We could relatively simply set up the parsers to whine if the find a deprecated function in the old place and not parse it at all in the new place.  

This can (as discussed) all happen post 3.0.  For 3.0 all that would need to be done would be to structure the documentation in terms of the file layout we want to move to and have for each element type a "where to find it in shibboleth2.xm".

This seems more natural to me and has as a benefit a greater granularity of control with respect to reloading metadata (and I guess signing and trust and so on).

I suspect I'm missing some subtle detail of configuration (e.g. per RP metadata or some such) or perhaps some philosophical issue I'm not aware of, but I thought I should share the idea.

Same resolution as

— The decision here is to leave things as is.  Just to not document them; For my own sanity I am collecting these things together here