OK, I understand it more now I've looked at the examples, and actually written one from scratch. What would really explain it well would be an XML Schema for the schema customization xml.
The documentation would be clearer if the "Schema component customizations" section were expanded to say something like:
"Specific schema components may be customized by creating an element named with the type of schema component, which must be one of
- (list any other types that are supported)
The path and name attributes, along with the nesting of the schema component customizations, are used to match the specific schema component. Namespaces are ignored.
All schema component customizations can use any of the nesting customization attributes defined in the last section, and also the following attributes:
Also I think the start of "Nesting customizations" could be simplified to read:
"Nesting customization attributes can be used on any customization element, including 'schema-set', 'schema' and schema component customizations. Here's the alphabetical list of these attributes:"
The example in "Customization document structure" should have ignore="true" rather than generation="skip".