Document compliance boundaries

[strogonoff]

We should specify which parts of style guides we intend to comply with and which parts we don’t.

From: metanorma/mn-samples-plateau#368

following the style guide in web-rendered version is not feasible in Firelight and trying to achieve that will negatively affect areas where Firelight can offer unique benefit compared to PDF and other formats. Perhaps we need to set compliance boundaries somewhere instead of going by the vibe, and recognize that we can solve for exact style guide compliance in some deliverables, while optimizing for other features (in case of Firelight, machine readable output, new ways of navigating and exploring data, versioning/diffing, etc.) at the expense of style guide compliance in other deliverables.

[ReesePlews]

hello @strogonoff thank you for bringing up this topic.

one area i remember where there were significant discussions were various notes in tables were not directly referenced "close" to the table, either in the bottom cell of the table or directly outside of the table.

i recall you did fix these issues either partly or totally, but it was these type of issues that were different from the "paged" document (metanorma .pdf) vs a web document (Firelight).

in a paged document the "footnotes in the page" are listed at the bottom of each page where they occur, but in Firelight, since there are "no pages" a footnote may be at the end of a sub-clause. that makes it difficult for the reader to scroll significantly far from the position where the footnote reference was to where the footnote description is visible.

here too, you fixed these after various discussions. so these were just examples.

i am sure there are other items too, which i am not remembering now. it would be good to come back to this after discussion with the client.

thank you for continuing to work on Firelight and for checking the earlier feedback issues.

[strogonoff]

To clarify what I mean (as I wrote to Ronald off Github):

I see often Firelight rendering to be compared to PDF. Sometimes I am told “Firelight shows content that is not included in PDF, and we should not show it”, or “Firelight shows content differently than a PDF”.

However, it seems to be a mistake to anchor to PDF. Firelight output should not be compared to PDF, it should be compared to websites. It is a different type of media.

Like with other websites (e.g., BIPM, GR, etc.) it can show more than an old style PDF/MS Word document would, it can show it in a better way, and it should. It does not compete with printed standards and their quirky style guides. Rather, it is an evolution step between that and a “smart standard” interface that focuses on semantics and relations.

The benefit compared to those other regular sites, though, is that it is rendered using the same data that can, with Metanorma’s help, also render a PDF or MS Word. It allows to author data once at highest fidelity, and then get data rendered according to the capabilities of each medium. In other words, with Metanorma + Firelight we can supersede both PDF publications and website publications, and I believe the latter is more strategic for us than the former.

After all, print media/PDF has much lower capabilities than a Web page or especially a Web app. The latter allows outputting strongly normalized machine-readable form, a form aimed at convenient exploration by a human, etc.

The caveat is that it is infeasible to use all those capabilities to their full potential while having to comply with style guides that written for a different medium with drastically more limited capabilities.

I think publishers should agree that expecting a website to comply with different style guides that were created for printed paper is unreasonable?