search

poseidon-framework / poseidon-framework.github.io

Main landing page for getting information about the Poseidon project
https://www.poseidon-adna.org
4 stars 2 forks source link

apply RCF2119 wording #69

Closed TCLamnidis closed 5 months ago

TCLamnidis commented 5 months ago

This PR applies RCF2119 wording to all columns. This is an optional additional change to those added in #68 .

In some cases, deciding if the right word is SHOULD, MAY or MUST got a bit tricky with cross-column validation, so maybe someone needs to double-check.

nevrome commented 5 months ago

I think it is better to avoid formalized language in this supplementary documentation. It is not part of the standard, but only a possible interpretation of it. This already becomes clear from the abundance of SHOULD and MAY statements here.

I know that the role of this documentation OUTSIDE of the standard has been a point of discussion in the past, and I'm glad to see the alternative written out in this PR once. For me it shows that it does indeed not work well as a normative document. E.g.:

The Poseidon_ID column MUST represent each sample with an ideally world-wide unique identifier...

How can something be a MUST when we wish it to be ideally unique? In the schema we can clearly say that one package must have unique IDs. But in this more interpretative document we can make less authoritative statements. For that to work, though, we have to avoid the language of the standard.

The column Alternative_IDs SHOULD provide... The Collection_ID column MAY store...

Why is one a SHOULD and the other a MAY? Where do we draw this (new?) line between different optional columns?

Also: If we double these statements about what should and must be there from the schema, then we also have to remember to update them between the documents if we apply changes.

TCLamnidis commented 5 months ago

I do agree that this is not the correct place to apply this kind of wording, honestly. I wanted to give it a go just in case we wanted to be more specific here, while saving time in future editing if that were the case. Overall I don't think it actually helps make the details more accessible or easier for users to read and fill-in their jannos

stschiff commented 5 months ago

Hmm, a lot of work, Thiseas, thanks a lot. I admit I'm also hesitant to put this in here - after having seen it. What do you think, what shall we do with this?

TCLamnidis commented 5 months ago

I think this served as a good proof to me as well that this doesn't really make sense to do or this page. I will close this PR. At least now we KNOW we don't want it. 😃