How Much Tag Set Documentation is Needed?

How much is too much?

Debbie Lapeyre

Senior XML/XSLT Consultant
Mulberry Technologies, Inc.


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?

Table of Contents

What is an XML Tag Set?
The Documentation Cliches
Planning Considerations for documenting tag sets
Scope of the documentation
Management, Governance and Support
JATS Documentation
Why talk JATS documentation?
Diving into the JATS Documentation
Opening and closing subsections on a page
Cross references
Top-level element in the Schema
Elements Pages
Attributes on an element page
Models and Context
Tagged Samples
Other sections on the Element Pages
Attribute Pages
Finding Information Pages
Stupid navigation tricks
The rest of the Tag Library
Getting Started (for the casual user and newbies)
Hierarchy Diagrams
For the Frequent user
Multiple labeled samples per element
Full article samples
Common Tagging Practice essays (almost tutorials)
Technical Details
Inconvenient truths and lessons learned
Aside: Rome was not built in a day
Discussion Topics
JATS-specific Questions
Questions about samples
General Documentation Questions
And in conclusion...
Other Resources to Support JATS Users
JATS-List and the Archives of JATS-List
JATS4R (JATS for Reuse)
JATS4R Recommendations
JATS4R Validation Tool
JATS-Con and the JATS-Con Proceedings
NISO site for comments/suggestions
Local Guidelines