Create ERA page

[fred-atherden]

• [x] Create page
• [x] Add description of what is being covered
• [ ] Add description of checks required on this content, compiled from current protocol documents
• [x] Add examples covering correct and incorrect scenarios, as required to support checks
• [x] Review house style document to ensure all requirements are covered by GitBook
• [x] Becky approved page
• [x] Melissa approved page
• [ ] Fred approved page
• [x] James approved page
• [x] Naushin approved page
• [ ] Share page with Exeter and invite feedback if relevant

Definition of done

• [x] Page revised after team comments
• [x] Team reviewed and approved page?

[fred-atherden]

@JGilbert-eLife, @Melissa37, @naushinthomson, @bcollins14 first draft of the ERA page is here.

It's a bit of a work in progress, for example there's a section on the QC which I will flesh out once we have some good examples, and have been through (at least) one for real.

Please note that there are some links (to a blog post and example articles) will not work until they are published (which is yet TBC).

Where should this page be placed in the sidebar? Under Toolkit? I feel like it isn't really suitable there, but equally I'm unsure whether it's suitable under content.

[Melissa37]

If any figures are drastically different from the original, then check these with the authors. There may however be perfectly acceptable reason why they are different

Suggest changing to:

If any figures are drastically different from the original, then check these with the authors. There may, however, be perfectly acceptable reasons why they are different

[Melissa37]

When an article is ERA'd, eLife JATS XML is converted to Schema.org using Encoda. It is then converted into the authors selected format (again, using Encoda).

author's

[Melissa37]

There are four steps to publishing an ERA:

1. Obtain the relevant links from the Stencila Hub project.
2. Edit this YAML file, and publish as a separate branch.
3. Create a pull request with the master branch and merge.
4. Run Jenkins pipeline to effectuate changes onto Journal.

This is a numbered list - I think it would help to number the corresponding titles below to match and maybe turn the four steps into links to the title in the next sections?

[Melissa37]

Create a new branch (based off the master branch), calling it something appropriate like era-update.

Might need to give further instructions on how to create a new branch?

[Melissa37]

Looks good, thanks!

[fred-atherden]

There are four steps to publishing an ERA:

1. Obtain the relevant links from the Stencila Hub project.
2. Edit this YAML file, and publish as a separate branch.
3. Create a pull request with the master branch and merge.
4. Run Jenkins pipeline to effectuate changes onto Journal.

This is a numbered list - I think it would help to number the corresponding titles below to match and maybe turn the four steps into links to the title in the next sections?

OK. I have added the numbers, but have not linked, because there is already a link in the second item of that list and I would like to retain it.

[fred-atherden]

Create a new branch (based off the master branch), calling it something appropriate like era-update.

Might need to give further instructions on how to create a new branch?

Yup, I had imagined that this would be more suitable on a different page, such as the GitHub one. But will defer to the consensus.

[JGilbert-eLife]

I wonder if we need more details about the pull request process - or should that go on another page? Otherwise seems good to me.

[naushinthomson]

Point of contact for Authors who are ERA-ing their article. If they have any technical questions, these should be directed to Stencila. However, any questions related to how they should present their content (and so on) are for Production to answer.

Should we clarify who/what stencila is?

[naushinthomson]

Re: known supported and unsupported content, what do we do with unsupported content and content issues?

[naushinthomson]

2. Editing the YAML file
3. Clone the elifesciences/builder-configuration GitHub repo locally. (Skip if already done).

I think this will also need to be explained on a GitHub page or otherwise, I'm not really sure what it means to clone a repo locally.

[naushinthomson]

I think otherwise, all good from me!

[fred-atherden]

I wonder if we need more details about the pull request process - or should that go on another page? Otherwise seems good to me.

Yeah, it's still being hashed out what the PR process is. So far, any PR has to merged by a dev (although which dev(s) have the permissions to do so keeps changing). I will update this page once it's fully established. (I would hope that we can do so, so that there are no delays, but that might be utopian)

2. Editing the YAML file Clone the elifesciences/builder-configuration GitHub repo locally. (Skip if already done).

I think this will also need to be explained on a GitHub page or otherwise, I'm not really sure what it means to clone a repo locally.

Agreed - I think this should be placed on a GitHub tool page.

[fred-atherden]

@naushinthomson any thoughts on this question I had?

Where should this page be placed in the sidebar? Under Toolkit?

[fred-atherden]

Point of contact for Authors who are ERA-ing their article. If they have any technical questions, these should be directed to Stencila. However, any questions related to how they should present their content (and so on) are for Production to answer.

Should we clarify who/what stencila is?

I've added a Who are 'Stencila' section.

[fred-atherden]

Re: known supported and unsupported content, what do we do with unsupported content and content issues?

Good question. At the moment, it's a judgement call. Anything that requires development work by Stencila should probably not hold up publication (unless it's critical to the understanding of the content - which you should be able to determine with the help of the author(s)). I'll update.

[naushinthomson]

@naushinthomson any thoughts on this question I had?

Where should this page be placed in the sidebar? Under Toolkit?

Oops sorry! I think that is the best place for it at the moment, unless we make a new section called 'Innovation' or 'Technology' or something similar?

[bcollins14]

Just noticed a lower case at the start of a sentence 'in other words, there is no difference in display between...'

[bcollins14]

Thanks Fred! I previously found these articles scary and even though I still do, its great to have more guidance ^_^

[fred-atherden]

Thanks - that's everyone and, aside from stuff I can't fully flesh out at this stage and a separate page about how to clone, PR etc. in Git, I think we're done.