Guidelines and Methodology for Creating SportsML Plug-in DTDs

1. Check in with SportsML Chairman to see if anyone else is working on or wants to work on this Plug-in
   • Certain specific DTDs will be in such demand that official SportsML subcommittees will be formed to develop them. In these instances, a subcommittee chairman may be appointed
2. Get to know the SportsML Core DTD
   • Read through all the internal documentation
   • Browse through several document instances
3. Take a look at some of the Specific DTDs already created
   • Especially review ones that have sports along the same lines as the sport you are looking to build out
4. Create a "data inventory worksheet"
   • Download the sample data inventory workbook
   • This workbook has sample "data inventory worksheets" for the Core DTD and for 7 specific DTDs
   • Note that the properties listed in these sample worksheets do not line up exactly with what wound up in the Official SportsML 1.0 DTD
   • Work as a team to list and list categorize all the properties for your sport
     • Do not worry at first about whether a property will wind up being an element, an attribute, a container element for other elements, or whatever. Just make lists.
     • Fill in the sample-values columns when applicable with representative samples.
     • Fill in the descriptions columns when properties are not self-evident
     • Try to organize the properties into sensible groups
       • For example, for many sports, stats can be grouped into "offensive" and "defensive" categories.
     • Try to cover all the major properties -- ones that would have a wide range of use. Other minor properties and stats can be added later.
     • If the value of one property can be derived from others, state the formula in the description column.
5. Based on the worksheet you've created, come up with some "straw-man" document instances that use XML elements and attributes to describe the content.
   • Follow SportsML style, using hyphens and naming conventions, for example:
     • Sample names for basketball team-stat elements:
       • stats-basketball-offensive
       • stats-basketball-rebounding
       • stats-basketball-defensive
     • Sample names for basketball team-stats attributes:
       • field-goals-made
       • field-goals-attempted
       • field-goals-percentage
       • field-goals-per-game
       • field-goals-attempted-per-game
       • field-goals-percentage-adjusted
     • Sample names for basketball action elements:
       • action-basketball-substitution
       • action-basketball-score-attempt
       • action-basketball-score
       • action-basketball-penalty
       • action-basketball-timeout
     • SportsML tries to stay consistent when possible, calling a pitcher-change in baseball, a goalie-change in hockey, and a player-change in basketball each a substitution.
   • If relevant, try to come up with sample XML markup for each major "specific DTD" section you'll want to use:
     • event-metadata-SPORT_NAME_HERE
       
       
     • team-metadata-SPORT_NAME_HERE
     • team-stats-SPORT_NAME_HERE
       
       
     • player-metadata-SPORT_NAME_HERE
     • player-stats-SPORT_NAME_HERE
       
       
     • official-metadata-SPORT_NAME_HERE
     • official-stats-SPORT_NAME_HERE
       
       
     • associate-metadata-SPORT_NAME_HERE
     • associate-stats-SPORT_NAME_HERE
       
       
     • tournament-metadata-SPORT_NAME_HERE
     • tournament-division-metadata-SPORT_NAME_HERE
       
       
     • event-actions-SPORT_NAME_HERE
   • Try to come up with sample XML markup for each major Core DTD section:
     • <sports-event>
     • <tournament>
     • <schedule>
     • <standing>
     • <statistic>
     • <article> (this one doesn't use any "specific DTD" elements)
6. Share your sample document instances with the SportsML Chair and possibly other SportsML authoring veterans, such as Johan.
7. Incorporate the feedback from SportsML heads and from other reviewers
8. Create the draft DTD from the sample document instances.
   • Start early on the documentation. Follow the documentation conventions in the other DTDs, since that format must be followed in order for the HTML documentation pages to be generated.
9. Also create the companion Controlled Vocabulary files, in plain-text format
   • These tab-separated files, which also should include documentation, are also compiled automatically to create the HTML documentation pages, and also the XML "topic-set" resource files.
10. Circulate the DTDs for comments. Fill in the blanks.
11. Validate your sample document instances against the Core DTD + newly-created Plug-in DTD. These samples should be made ready for posting on the SportsML examples page. Update the samples so that:
    • They are 100% valid
    • They take advantage of as many of your DTD's elements and attributes as possible (and as sensible)
12. Congratulations! Your new SportsML plug-in is now ready to be voted in as "Official SportsML!"