The three-part workshop series “Sharing What You Did: Documenting Text Analysis Research with Voyant and Spyral”
focused on a core research challenge in Digital Humanities: not just producing results, but documenting the analytical path
so others can understand, rerun, and adapt the work.Led by Professor Geoffrey Rockwell, the series moved participants through a progressive sequence:
(1) explore text in Voyant Tools, (2) export analytical steps into a Spyral notebook,
and (3) save, share, and refine notebooks as reusable research artifacts.
Augustine A Farinola supported the workshop delivery, assisting with preparation, monitoring
participant questions, and helping with in-session troubleshooting and follow-up. The sessions also benefited from technical
support and clarifications from Andrew McDonald, who is programmer supporting
Voyant/Spyral development.
Purpose and framing: from exploration to transparent documentation
The workshop’s premise was that exploratory text analysis is often hard to “show” responsibly. Voyant makes it easy to move
quickly—testing terms, shifting views, and generating interactive panels. But those same strengths can make it difficult to
reconstruct what happened later, or to communicate the analysis to collaborators, reviewers, students, or the public.
“When you’re studying a literary text, you always want to be able to get down to the raw text.”
This principle—moving fluidly between summaries and textual evidence—became the baseline for the series. Spyral, introduced
as a notebook environment (using JavaScript), was presented as the layer that turns exploratory work into a documented,
shareable research narrative.
Session 1: From Voyant exploration to a research-ready notebook
At this session,
participants learned how Voyant’s linked panels support rapid exploration while remaining anchored to textual evidence,
then practiced exporting a Voyant view into Spyral to begin a shareable research notebook.
The session introduced participants to Voyant’s interaction model: uploading or loading text, working across synchronized
panels, and using the interface to explore terms, contexts, and distributions. The session then established the key workflow
that structured the entire series: From Voyant Tools → Export → Spyral notebook.
The export action generates a notebook scaffold containing a code cell to load a corpus (or refer to a corpus ID) and a code
cell to recreate the chosen tool panel (including parameters, if used). This made a central point tangible: researchers do
not have to start by writing code from scratch. Instead, they can begin by exporting working examples, then gradually learn
how to read and adjust what the tools produce.
Session 2: Saving properly, persistence, and responsible sharing
At this Session,
the focus shifted to durable practice: GitHub authentication, saving notebooks to the Spyral server, sharing stable links,
and adopting reproducibility habits (e.g., keeping originals and exporting HTML).
The session addressed how to save notebooks reliably and return to them later—not as static exports, but as editable, living
research documents. A major focus was authentication and persistence via GitHub sign-in.
“It’s not actually stored in GitHub… we’re simply using GitHub to authenticate you.”
Participants learned how saving works in practice—using cloud save controls, managing notebook metadata and visibility, and
sharing URLs once notebooks are saved to the Spyral server. Session 2 also emphasized sustainability and research care,
noting the importance of preserving original texts and stable exports for citation and publication contexts.
“You should always make sure that you keep the original texts…”
Session 3: Review, participant sharing, and learning to read code
At this session,
participants consolidated the workflow through review and notebook sharing, then leveled up with “forking” norms and
beginner-friendly code literacy—reading and adapting exported JavaScript rather than writing from scratch.
This session reinforced skills through a review notebook and then shifted to collaborative discussion: participants were
invited to share notebooks they had been building, ask questions, and troubleshoot workflows collectively.
Being the final session, the instructor also introduced an important next step in notebook literacy: not writing JavaScript from scratch, but
learning how to read, understand, and adapt code produced by exports and examples.
The session reinforced iterative learning and community support, acknowledging that notebook-building takes repetition and
revision.
Take Home Skills for Participants
Voyant fundamentals for exploratory analysis: loading texts/corpora; navigating synchronized panels; moving from visualization to textual evidence.
Exporting analytical steps into Spyral: capturing a Voyant tool view as runnable notebook code (including parameters/queries).
Notebook composition as scholarly documentation: integrating narrative text cells with code cells to explain aims, methods, and interpretation.
Saving and sharing responsibly: GitHub sign-in for authentication; server-based saving; shareable notebook URLs.
Versioning and reuse norms (“Save As” / forking): creating personal copies for modification while preserving original notebooks.
Reproducibility practices: using corpus IDs and controlled loading strategies; keeping originals; exporting stable HTML for archiving.
Intro code literacy: reading and lightly adapting JavaScript examples; understanding parameters and small edits that change outputs.
Acknowledgements
The workshop was organized through Bridging Divides (Toronto Metropolitan University). and Professor Yasmine Abu-Laban of the University of Alberta .