Improve Documentation

[ohzqq]

I'm currently making an application for managing my audiobooks and ebooks, based on databases maintained by Calibre. At the core is an API for serving metadata. Since I already have the metadata being serialized in JSON, I figured why not try to output it in some kind of standardized format, primarily OPDS 2.0. While I know this isn't maintained by Readium, the website indicates that "Metadata expression in OPDS 2.0 is based on the Readium Web Publication Manifest model and its default context".

So I obviously turned my attention towards this project only to find that the documentation on the metadata format is... seriously lacking.

My first question was "how do you express the existence of more than one author?" and I can't (easily) find an explicit reference to this. I ended up digging into the go toolkit to figure out that, yes, you can use a JSON array to indicate the presence of several contributors of the same type. The two examples provided in the repo only have single contributors for any given role.

It's equally unhelpful that a link is provided to the W3C's definition of a web publication, since they have their own standard for metadata. I can also see an open github issue discussing support for their manifest. I first looked at their manifest for guidance since the README links to it, except that there are clear differences.

Since my application is mainly geared towards audiobooks, I also looked to the audiobook profile for guidance. In Appendix A, a link is provided to the IA's OPDS feed... which is still in XML.

The documentation on all of this is too sparse. Approaching this project as a librarian and a coder leaves me at a complete loss as to how I can effectively incorporate this into my current project. I'd very much like to apply and use this standard, I'm just unclear as to how I can proceed, based on the current documentation.