Authoring guidelines?

[JayPanoz]

Do we want to provide authors with public guidelines like iBooks Asset Guide or Kobo ePub Guidelines?

Documentation is indeed very sparse, which has been a significant and constant issue, and I’ve personally had instances which could serve as authoring guidelines in ReadiumCSS e.g. internationalization.

The tricky part is that, obviously, those two examples are Reading Apps Guidelines, while we’re a RS (SDK). But it could at least help authors to have guidelines related to the .opf, maybe markup (epub:type), and EPUB feature status (as that could also help potential contributors have a better sense of prioritization?).

Another tricky part, obviously, is that this is quite a lot of work… but if we start with something minimal, it will be better than nothing at all.

[llemeurfr]

Many specificities of Readium EPUB handling will come from the navigator an especially the way Readium CSS is "programmed". Therefore even if we provide an SDK, I suspect that every reading system based on our SDK will have the same requirements re. EPUB content. From this I infer that we CAN produce such guidelines.

I imagine the hard work needed to get a full set of guidelines, and therefore I would dream the the EPUB test suite + the EPUB authoring guidelines that the W3C Publishing CG SHOULD write could participate to this effort. But this won't come before long.

So yes, I'm in favor of writing a minimal documentation on what authors should or shouldn't do if they want full Readium-2 RS support. By the way I see that the iBook document is not really big.

[JayPanoz]

I can isolate the significant parts of ReadiumCSS to kickstart such a doc (and PR a markdown doc in this repo) but other metadata, and opf more generally, would have to be tackled by someone familiar with the streamer.

The navigator is another story entirely. We’ve discussed quite a lot actually (title in the header, what should go in the footer, footnotes, etc.) but that spans like 8 months of engineering calls. So I can also try layout out the foundations there but any help would be appreciated.

[JayPanoz]

Started working on this doc, which can be found @ https://github.com/JayPanoz/architecture/blob/88acc00bd301ac291f9c78cc49bd8daa0286081e/other/authoring-guidelines.md

Please let me know if this is going in the right direction – it’s kinda difficult to keep it to the bare minimum.