First Handbook Hackathon

On June 27th, 2024, the first hackathon for the Research Support Handbook took place with all the post authors. For this hackathon, we focused on non-GitHub based contributions, to make it as easy as possible to contribute. To make getting started with contributing easier, we created a choose your own adventure game. We document some lessons and clarifications below, in addition to the twelve reported problems and suggested changes.

The workshop helped articulate the dynamic relation between topics and pathways. Topics are contained pages around a specific subject; pathways are a collection of topics. This means that pathways include the topics directly and that this content should be up to date at any given time. When topics are changed, pathways are dynamically updated, making sure there are no discrepancies. The only situation where this may not be the case, is when a pathway is still a work in progress and the topics are not yet properly linked.

Pathways will become more efficient to create as we include more topics in the handbook. Given that pathways are primarily collections of topics, this means that there is barely any new content in there, if any at all. As we include more topics (eight at this time), pathways can focus more and more on the structuring of content, and focus less on creating the content itself.

With new contributions, contributors surfaced the need to preview the changes to the handbook. We documented two ways to render the handbook for such previews: (1) creating a Pull Request automatically deploys a preview website and (2) running quarto render locally on the code. Option 1 requires no additional software to be installed, but requires some knowledge of GitHub. Option 2 does not require much knowledge of GitHub, but requires the Quarto software to be installed. There was also the note that deploying the handbook using GitHub pages required a change to the URL, which may cause issues when merging the changes back into the main handbook. This highlights that ensuring reliable previews of contributed content is of importance to some contributors to the handbook.

Lastly, the hackathon surfaced many questions and discussions around the collaborative decisions that will need to be made. When does a topic become too long and should it be split up into multiple topics? Can a topic include subtopics? How is the GitHub environment maintained? How much technical expertise is necessary to ensure the content does not go offline? What contributor roles are there and who has which role? How do roles get distributed and can people volunteer for them? This highlights the engagement with the handbook, and we encourage everyone (including ourselves) to generously surface these discussions in issues or in a next hackathon.

In summary, the first hackathon is a success! This is the start of the next phase of the handbook journey, moving from design and scaffolding to nurturing and growing the contents. There will be more hackathons, and these will be announced on this blog and on other channels at VU Amsterdam. Until the next one!