Like we do with the namespace documentation, it would be great to generate the descriptor documentation from the descriptor XSD files. For example, if you look at the AndroMDA configuration documentation:
http://team.andromda.org/docs/configuration.html#andromda, you'll see we describe each descriptor (its element and attributes). This information could be generated from the XSD files in the core and the documentation extracted from those (since we can embed xs:documentation elements), so that we don't need to maintain the information in two places.
Improvement
Open
Major