You Only Write Thrice

Creating Documents, Computational Notebooks and Presentations From a Single Source




Kacper Sokol
and Peter Flach

These slides are also available as an article page, which explains how to launch them as a Jupyter Notebook or interactive slides.

Hello Everybody, I'm Kacper and in this talk I'll show you our idea for an end-to-end, transparent publishing workflow, which makes the entire process easier for academics.

Publishing Process

Stagnation

Can you spot a difference between these two publishing formats? The one on the left is a photo of a manuscript -- a physical printout. The one on the right is a screenshot of a PDF. Not much of a difference after all.

PDFs are ubiquitous these days. They are easier to distribute and copy, but have the same limitations as paper printouts.

Ideas: distill.pub

In [4]:
preview_url(DISTILL, height=500)
Out[4]:

Ideas: OpenReview

surrogate

Ideas: The Open Journals (The Journal of Open Source Software)

surrogate

Issues

  • Standalone tools
    • Not integrated
    • Lack of a dedicated process
  • Not covering the entire publishing process
    • Compose (write / revise)
    • Review (comment / rebut)
    • Publish (format / version)

Format Multiplicity

(Conference) Publishing


  • Manuscripts
  • Presentations
  • Posters
  • Promotional videos
  • Press releases
  • Blog posts
  • Source code
  • Computational examples
  • ...
  • Reviews
  • Revisions
  • Versions

Source Formats

  • $\LaTeX$ documents and Beamer slides
  • Microsoft Word / OpenOffice Writer / Google Docs
  • Microsoft PowerPoint / OpenOffice Impress / Google Slides
  • Markdown / HTML (and other web technologies such as JavaScript)
  • Code hosted on Dropbox / GitHub / BitBucket
  • Jupyter Notebooks / CodaLab documents
Multiple (out-of-sync) copies of the same content in different formats

Lowest Common Denominator: Static Outputs and Artefacts

Artefacts reusability:

  • visualisations / figures
  • tables
  • code snippets
  • mathematical typesetting

enforces their simplest – often static – type

Towards Online and Interactive Research Outputs

Authoring

Multiple Entry Points – Single Source

MyST Markdown →

  • Jupyter Notebook – computational narrative
    • Google Colab
    • MyBinder
  • Reveal.JS – interactive slides
  • Jupyter Book – interactive report/document/book

Version-controlled Environment

  • Source versioning and history tracking
  • E.g., git or mercurial

Reviewing

  • Akin to source code review, e.g., through Issues and Pull Requests infrastructure
  • Permanently attached to the document source
    • Provenance record
    • Resubmission history
  • Conversational review with inline comments and discussions
surrogate

Publishing

  • Tag a version
  • Release to an archiving platform

Bibliometrics

  • DOI minting (e.g., Zenodo) to support citations
  • Google Analytics-like dissemination tracking

Presenting

  • Three formats: documents, slides and computational notebooks
  • Native interactivity support
  • Improved accessibility
    • Execute directly in the browser – no need to install stuff
    • Support for web-enabled assistive technologies
  • Web technologies are the limit
In [5]:
interactive_plot()

The Way Forward

  • Extend the Jupyter Book / Sphinx plugin ecosystem
    • Support non-mainstream programming languages (SWI Prolog, ProbLog and cplint)
    • Linked exercise and solution blocks
    • Custom code syntax highlighting
  • Bespoke publishing lifecycle platform (instead of GitHub or BitBucket)
  • Compute resources suitable for hosting and executing the (interactive) content

Horizon 2020 ICT-48 European AI excellence centre exploring new ways of working and AI-powered research and collaboration tools.

Exhibit

Source

https://github.com/so-cool/you-only-write-thrice/

surrogate

Preview

https://so-cool.github.io/you-only-write-thrice/

In [6]:
preview_url(YOU_ONLY_WRITE_THRICE, height=500)
Out[6]:

Thank You!




K.Sokol@bristol.ac.uk