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)
- All the code and documentation is in version control.
- All the data is archived in figshare, as a SQLite database.
- The paper is written in HTML, with figures as SVG images drawn using JavaScript.
- The data is continuously updated in the background, and the figures and text are updated in real time.
- The paper is hosted on the author’s own domain. In theory this is good, but as it’s published in a system that doesn’t yet have version control, there’s no ability to compare past versions. That’s ok though, as long as it’s saved in the Internet Archive whenever someone refers to it.
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.