search

o2r-project / erc-spec

Executable Research Compendium specification and guides
https://o2r.info/erc-spec/
Creative Commons Zero v1.0 Universal
7 stars 5 forks source link

Add to user guide: the ERC as journal supplement #37

Closed ghost closed 6 years ago

ghost commented 7 years ago

minimal draft, that can be extended in the future.

ghost commented 6 years ago

closed by df7e904c8bedf527f729a5a43fd0040e0085cc8d

nuest commented 6 years ago

Some comments on the draft:

ghost commented 6 years ago

add link to FAIR website and/or publication

Should a spec include such links? I think, not.

What about multiple ERCs as supplements for the same publication?

Right. That could be a scenario, though I can't find a good reason why it would come to be.

Do we have some way of linking to the respective publication from erc.yml that we should mention in that guide? Would be nice to have.

What about a pre-reserved persistent identifier?

What do you think about the following: "A publication platform may identify a supplement as being an >ERC by checking the existence of the configuration file in the packaged ERC, i.e. /data/erc.yml, and unpack/render the contents accordingly, e.g. for ERC inspection."

I like that but we would have to specify, how to render the ERC.

nuest commented 6 years ago

Re. link to FAIR: You added a link to the Greenbaum paper, so that readers can "read more", so why not include a link to a paper to explain the FAIR principles in detail?

I am not aware of any recommendations on which links not to include in specs, pointers welcome.

Multiple supplements: If I have multiple scenarios or multiple plots packaged independently, it actually makes linking to them and embedding them into an article view easier, because if I have one large R Markdown document with 5 figures, I actually must link to a part of an ERC, which is something we have not yet thought about. If each figure is an ERC, you can just show the view file and know it will show the correct figure.

Re. link to pub: Yes, a DOI would be good. My question was actually more about the "How and where", not about the "what": Do we have a field in erc.yml where we can put the DOI? AFAICS we do not have that yet.

Re. ERC identification: I disagree. My suggested sentence describes how to identify an ERC, and if identified as one a supplement can be rendered. And we actually already do specify that, because we say an ERC must have a view file, which must be HTML.

ghost commented 6 years ago

Links/fair: Yes, I included the Greenbaum paper to close an issue. I am biased by a preservationist perspective on the spec, that drives me into thinking all weblinks are non persistent and thus adding future gaps to the spec.

Multi supplements: I would say splitting up plots or other attachments contradicts the idea of having a "bundle". On the other hand it might make the ERC more "micro" which opens up other opportunities.

Link to pub: Right, that element would have to be added. Instead of calling it DOI, I would prefer something like generic identifier or pi. To indicate that the governing publication is meant, we could label the element relatedIdentifiers as done in datacite md.

ERC identification: Then we have that already. It only needs an instruction on how to call or access the included rendering. I thought within a supplemental ERC, the view file would not only be obsolete but a potential conflict of contents.

nuest commented 6 years ago

Nobody cares about our spec :-). Any link we include is much more likely to exist longer than the current draft of our specification. I cannot remember the name now, but some uni offered a service to proxy URLs for citation (caching the contents)... if I can recall the name and find the resource more trustworth, then we could cite that instead of the original URL.

Re "micro": Yes, that was my idea, being more open/flexible, it would fit our "evolutionary approach", which is already implied by having the ERC as a supplement. Micro-ERCs just take the supplement a bit further.

:+1: for relatedIdentifiers. Since you know how it's done in Datacite, can you create an issue?

Re. conflict of contents: I also this this conflict, but thinking about ERC supplements and the evolutionary approach, I think we have to live with this potential for now. The instruction to access it is also already there (unpack, parse erc.yml, open viewfile), so let's close that part by saying: We must clarify in the spec how to easily identify a BagIt bag as an ERC.

ghost commented 6 years ago

Nobody cares about our spec :-)

Sadly true. But that should not define our ambition.

👍 for relatedIdentifiers. Since you know how it's done in Datacite, can you create an issue?

See https://github.com/o2r-project/erc-spec/issues/43

nuest commented 6 years ago

Regarding external links: No it should not define our ambition, but it can keep us (for now) from fixing problems of the future (i.e., the spec is so widely used that we have to worry about external resources we link to not being available anymore).

Anyway, maybe this approach can mitigate your concerns, i.e. citing via web.archive.org ?

nuest commented 6 years ago

@7048730 What about using https://www.webcitation.org for external links in the spec?

https://www.force11.org/group/fairgroup/fairprinciples becomes https://www.webcitation.org/6tKGXxU17

ghost commented 6 years ago

I think, that is even worse, because it obfuscates the original link. When that website blacks out, there will be nothing left to reconstruct the linked content. Lets just stick with conventional links and focus on trying not to outsource too much content. That way all links will be references to "further reading" while the spec stays concise.