title	description	date
Science Communication with Notebooks		2022-12-09

:::{warning} In Progress!!

This document is an in-progress DRAFT aiming to provide recommendations and examples on how to use notebooks in publishing, including how to adapt and improve JATS, MECA, and other standards. The collaborations for starting these documents came out of Notebooks Now! (Stall et al., 2022, see recording).

:::

At Notebooks Now!, we looked at the academic publishing workflows around notebooks as a number of steps: (1) pre-submission, (2) submission & metadata, (3) editorial & peer review, and (4) production & post production. Each step of this workflow and how they fit together may be required to change or adapt when considering computational content in notebooks as a core publication artifact.

To archive, host, and disseminate scholarly articles publishers typeset author submissions. This process not only creates PDFs and websites, it also adds structured information around citations, cross-references, and other important attribution metadata (ORCIDs, funding identifiers, RoRs, and other PIDs) which are distributed to other participants in the ecosystem (e.g. PubMed, CrossRef, indexers, archivers, etc.). In the context of open access, it is now common¹ that this Version or Record (VoR) includes the full text of the article as well as figures and tables; it is no longer just the abstract, authors, and references. The full text is most often stored in an XML format which can be used to create all other views of this content (PDF, HTML). The structure of this XML varies between publisher, with the most used open standard being JATS (Journal Article Tag Suite), a NISO standard.

When considering how to include notebooks in publishing, identifying how to include the notebook content in the VoR will unlock all current downstream providers, and allows the use of notebooks in publishing to be broadly adopted. Here we will discuss the constraints of JATS, suggest missing components, and recommend community standards to support notebooks in the VoR. These are designed to support various use cases of browsing, replication, and distribution of these articles as executable documents. We also consider how these processes fit into author-driven workflows to allow for continuous updates, feedback, and iterations throughout the process of creating this structured data.

Contents

• Approach
• Notebooks as JATS
• MECA Notebooks
• Working Notes

---

This work is licensed under a Creative Commons Attribution 4.0 International License.

Footnotes

1. There are currently 5.8 million works with full-text XML available through CrossRef, for example. See CrossRef’s API. ↩