Publishing research on the web

·

In one day, two separate authors demonstrated that they’ve solved the problem of “how to publish your research on the web”.

Dominic Tarr analysed the performance of different JavaScript cryptographic libraries, and Jure Triglav collected tweets mentioning sunny weather and correlated them to actual weather reports.

The reports are online for anyone to read, and the code and data are in version-controlled repositories, with instructions for anyone to reproduce them.

What’s so good about these reports?

JS crypto benchmarks (Tarr)

  • All the code, data and documentation is in version control.
  • The README file describes the purpose of the project, the dependencies, what was tested, how to reproduce the experiments, and what license the project is released under.
  • All the data is published as CSV files.
  • The process for generating the data (a Bash script that calls node commands) is present, and its usage is documented in the human-readable README.
  • All the machine-readable metadata needed for the project, including the list of dependencies, is present in package.json.
  • The results are written up as a paper in Markdown (including figure images directly from the output folder).
  • For “maximum credibility”, a HTML version of the paper is typeset from the Markdown. This is most likely what people will see first, so it links to the code repository for all the information needed to repeat the experiments.
  • The paper is hosted with GitHub Pages, so any changes show up almost immediately, are tracked in version control, and can be accessed and compared to previous/subsequent versions.

Weather Tweets (Triglav)

Notes on hypertext

Note that neither of the reports have “references” sections at the end, for the simple reason that they don’t need to: if they need to refer to anything, they just need to link to it in the (hyper)text.