Abstract
The more documentation the better. Documentation is expensive, stick to the basics. If it isn't well documented people won't use it or, worse, won't use it consistently. We can't afford better documentation. We've all heard the cliches.
JATS (The Journal Article Tag Suite) has documentation — A LOT of documentation. Documentation designed to introduce new users to the tag set. Documentation designed to support experienced users. Documentation to support people who are customizing JATS, including advice on both the mechanics and the logic of making customizations. There are definitions, helpful remarks, tagged examples, extended essays. There is an International Standard that meets political needs and a site with non-normative documentation that meets practical needs. There are third party sites advising users on how to use the tag sets for best interoperability, and many organizations that ingest JATS provide (and may insist on) site-specific local rules.
It is entirely possible that JATS is the most heavily documented XML tag set of all time. Do other tag sets need this much documentation? Are there techniques other tag sets would find useful? After a guided tour of the JATS documentation, the audience can chime in: How much documentation does a tag set need? Do any tag sets need this much documentation? How much documentation does YOUR tag set need? What is useful? IS any of this overkill? What audience most needs to be served? What parts of the Tag Library you like? What parts not so much? How can we improve the JATS documentation?