MusicXML 4.0 Documentation Update

Our main outstanding issue for the MusicXML 4.0 release is including the full documentation in the Community Group Report. I am happy to announce that the first draft of the full MusicXML 4.0 documentation is now available to review at:

https://w3c.github.io/musicxml/

The documentation is built using the generator tool that Adrian Holovaty initially created for MNX. It takes the MusicXML 4.0 schema and converts it into a Django database, which we then edit to add examples and additional content like the tutorial. Edward O’Riordan from Soundslice contributed to the graphic design.

We believe this version of the documentation has several advantages compared to the previous documentation available for MusicXML 3.0, besides being up to date with the latest 4.0 features:

• The documentation now hides all the W3C XML Schema implementation details like complex types, attribute groups, and element groups. These are internal building blocks for the schema but of no immediate concern to MusicXML authors and developers. Now all you see are the parts of the schema that do matter to authors and developers: elements, attributes, and simple types (e.g. enumerations, regular expressions, different types of numeric values).
• The examples and the element documentation are automatically linked together. You can click on any element within an example and get taken to the element documentation. Within the element documentation, you automatically get a list of all the examples that use that element.
• The documentation is produced by an open source tool that anyone can use. Instructions are included in the Readme file within the MusicXML docgenerator directory.

Please take a look and let us know your thoughts. The documentation is not yet complete, but we think it is at a good enough state to be reviewed. We have brought over all the examples from the MusicXML 3.0 documentation, as well as the tutorial.

We know of four outstanding sets of issues that we are currently working to fix:

• The documentation for some complex types is being generated incorrectly. Some choices and sequences are not displayed accurately. Everything is correct in the database representation; there are some bugs in the automatic text generation that we need to fix.
• We need more examples. This is especially true for features added in MusicXML 3.1 and 4.0, but also for some older features where the MusicXML 3.0 documentation missed an example or had an incorrect example.
• We need to add the version history.
• The graphic design is still a work in progress.

If you have general comments and suggestions about the documentation structure and layout, please raise those in our main GitHub documentation issue 353. If something is incorrect in the description or example for a particular topic, please raise that as a separate issue if that seems appropriate. If you want to collect a bunch of comments in a single post in the main GitHub issue, that’s fine too.

We look forward to hearing your thoughts on the new documentation! We hope that you agree that it is a big step forward for making MusicXML easier to use and understand. But if you don’t, please let us know that too with suggestions on how to improve things.