A Tale of Reproducible Presentation Infrastructure
Some folks visiting this post will be interested in the high-level overview of FAIMS by Shawn Ross and Penny Crook as part of the AAO Seminar Series.
This post, however, is not about a high level overview of FAIMS. Instead, it’s about responsible academic research, slides as FAIR academic outputs via GitHub Releases, and automation of said releases using LaTeX, Overleaf, our new LaTeX Slide Template, Github Actions, and utterly failing1 the “Is it worth the time?” test for automation.
Specifically our goal is, for any presentation or output we have, to:
Have consistent branding without us fighting with closed-source software.2
Make sure we have good and transparent records of all of our outputs, so that we can reuse them, share them, and use them in future research. Being able to share an archive of presentations is a great way to provide future researchers deep insight into our project, costing us little time now but would be virtually impossible later.
Engage in open scholarship practices
Use version control for our slides and outputs so that we have a single authoritative thing without hundreds of copies named
Final_FAIMS_slides_updated_for_3_BBS_Final_Draft_20210819.pdfMake sure it’s archived on our OSF page.
Consistent branding using LaTeX
As the more astute readers will note, the slides used in the presentation (https://github.com/saross/FAIMS-intro/releases/tag/v4.0) are themed using LaTeX beamer slides inspired by Macquarie University branding rather than the new branding package done by Vel from LaTeX Typesetting3 (https://github.com/FAIMS/FAIMS3-Intro-Slides). The previous three presentations using this deck were done before we had the new slide template prepared and only after the presentation did I realise that I needed to port the presentation to the new version. This was relatively straightforward. The only difficulty of the port was figuring out a way to have a split bibliography4 so that we could have normal citations in the presentation, and our Zotero Library of FAIMS Publications (see also our website’s resources page). The benefit of solving this problem is that we can include our project citations in this overview presentation using proper APA-formatted citations as their own bibliography that is trivial to update as the project produces peer reviewed outputs.
In short, separating presentation from data will allow higher quality versions of this presentation going forward with less time invested during the inevitable crunch-time of preparing a presentation at the last minute. Having slides (on Overleaf) defined as:
\begin{frame}{Introduction to the FAIMS Project} \begin{itemize}
\item The Field Acquired Information Management Systems (FAIMS) Project began in 2012 as a national Australian information infrastructure project in archaeology.
\item Developed FAIMS Mobile for field data capture \parencite{Ballsun-Stanton2018-zd}.
\item Use expanded beyond archaeology to geoscience, ecology, ethnography, linguistics, oral history.
\item Has been customised for over 50 workflows at more than 30 projects.
\item Data and workflow modelling for customisations provided deep insights into field data capture and the infrastructure needed to support it.
\end{itemize}
\end{frame}
Means we can focus on updating and managing our text rather than fighting with Powerpoint over bullet size and alignment. BibLaTeX is a useful bonus as well, since few people expect a well formed bibliography in a normal slide deck.
Having a good project history and practicing open scholarship with an OSF project
It is important to us to publicly document and archive our intermediate project outputs as well as our formal documents. While archives of milestones and reports, along with peer reviewed articles are the backbone of our reporting, they do not capture all of our reporting on the progress of the project.
It is our hope that by documenting our presentations, our management techniques for academic software engineering (Part 1, Part 2), and providing a version history for our academic thought as well as our software, we can leave a better legacy of knowledge to future academics struggling with the same problems. Far too often have we looked at 1, 5, and 10 year old projects whose funding has run out — and whose project infrastructure has vanished like leaves on the wind. Since we were frustrated with the academic record, we decided to make a conscious effort to leave a lasting historical legacy5 using practices of open scholarship.
We have chosen to host all of our project outputs as components of our OSF FAIMS3 project because the Project > Component hierarchy fits this specific model than the flat “everything is a document” hierarchy of Zenodo. Zenodo, for this very same reason, is an excellent archive of our project formal reports which do not necessarily need to relate to each other, but need to have the document itself as the centre of attention.
Version control and GitHub Actions
Because we don’t have endless copies of files sitting around on our local disks, we are able to use Git to name and capture specific moments in time. By using proper naming conventions, we can provide far better metadata than a filename — as well as the opportunity to explore how a given presentation has changed throughout its iterations. This is as true for software as it is for academic research and outputs.
However, the process of compiling on Overleaf, saving, renaming, creating a release, and remembering to upload the right file to the release is mildly tedious. As such, once I was done migrating the presentation to the new format, I also wrote a Github Actions workflow (latex.yml) which could automatically produce and rename and attach the file. Thus, as new presentations are made and updated, we’ll never need to remember to attach a pdf downloaded from our local disks to achieve a scholastic record in GitHub releases. Soon, I hope to also automate the making of an OSF component, for even more automation and time-saving.
To be fair, actually looking at this chart — absent hyperbole — we do presentations a little less frequently than monthly, and the process of producing a release does take a little more than 5 minutes (give or take), so technically it’s not a failure per the chart — if one squints and is charitable. Pragmatically, it was also good practice using GitHub Actions, and good practice excuses many inefficiencies in the name of improving abilities.
Yes, we have a Google-slides version of our slide-branding template, because a) different project members have different levels of comfort with LaTeX and b) sometimes something ad hoc is needed, in a great hurry. We’re not perfect.
As someone who is “decent enough” at *TeX (I wrote my dissertation in ConTeXt, support open source journal typesetting, and have my students typeset their theses in LaTeX (MQ thesis LaTeX theme) — Vel’s LaTeX code is better and prettier than I could do in any reasonable time. I recommend his services.
I bet your slide deck doesn’t feature automatic citation management…
The relative proportion of historians and archaeologists amongst project leadership probably also has something to do with this decision.
For more news, subscribe!
