This past week, Connie and I spent most of our time learning the ins-and-outs of Wax. My primary activity was geared toward how to change the website’s style. Working with Wax brought up some key challenges related to technology choices into focus.

Sometimes when you’re working on a web development project with a small team, progress often takes longer than you think to start, but progresses faster than expected. As much as the ideal of iterative work lives on in project planning, most of our progress has some in fits and starts. Part of the slowness to is learning new domains, as required by sourcing the visual media for our archive. But another aspect, a focus of this post, has been learning technical tool from scratch.

While the Wax documentation owns up to a learning curve being “best suited for folks who are willing to take on some technical responsibility in exchange for a lot of flexibility,” the nature of statically generated site engines is that complexity is kept as minimal as possible. In fact, a Wax workflow image represents a basic explanation of how a Wax site as built. What I didn’t anticipate was the complication of additional framework/tools bundled with this particular library.

One example that we stumbled on several times during the stylistic changes was the inheritabilty of CSS/Sass used via Bootstrap. For two people with limited front end development experience, it’s hard to understand where to change fonts, colors for background, hover-overs links and text. The documentation suggests forking the Wax demo project from their repository then “clobbering” the collection using RAKE. These actions yield a complete, working set of styling and interactivity for the website with Bootstrap, but no straight forward landing spot for the new archivist without frontend design skills to update the design of their new website.

There are three Sass files in two directories that determine the CSS compiled when the site is generated.

Three Sass files in two directories

All three of these files interact and depend on each other in different ways. A couple of times during this week, we struggled to understand exactly how the update a font, or a hover over color. Should we update the font-family? What about the $body-text variable created via Sass? At best, we got a compile time error when we forget to add a semicolon. We were able to make stylistic changes in the end, but if we need to make additional changes, we might not exactly remember what we did, and whether or not all of the steps we took were necessary in the end.

Some other struggles came up beyond changing styles. We still haven’t discovered why about 20% of the images we’ve uploaded don’t render on our website. Debugging this is a challenge given the size of the Wax project.

Another slate of problems we didn’t foresee are related to performance from a developer perspective. From start to finish, generating the collection takes over two hours! If you add or remove images from a collection, it’s required to rebuild the entire collection, triggering a long process working through +500 images. In a similar vein, generating the static website currently takes more than twenty seconds locally, and six and a half minutes to be deployed. I consulted a friend who formerly used Jekyll for their personal development blog, and they claimed it told four hours to build two years worth of posts. My hunch is that this is related to Digital Humanities comfortability in shipping prototypes and smaller projects, and that our collection is a little too large for Jekyll generator, being built in Ruby, a relatively slow interpretative language. These performance issues almost led to us shifting our archive over to Hugo, a static site generator build in Go , which would ameliorate any performance issues, but we decided against it due to time constraints and the introduction to yet another topic to learn about.

As mentioned before, we will likely scale down the types of media available on the archive. Given the performance issues, we wouldn’t want to experiment heavily with embedding videos, and will opt to include those on a resources page with appropriate links. I suspect we’ll be learning more about the ins-and-outs of Bootstrap, CSS, and Sass for the next week to continue to form the website appropriately given our content. We also need to focus on furnishing the appropriate context and text for the archive to give vistors a sense of themes and purpose of the website sooner rather than later. I’m still confident we will meet our shipping date in two weeks, just that it will be a rough draft we’ll need to polish in the remaining two weeks of the class.

As Connie mentioned in her blog post this week, we started building the website for our archive. For me, it’s typically nerve-racking to start to show work in process. This is especially true on a subject that I find fascinating and worthy of exploration for beyond the end product due for this class. After hearing some conflicting ideas about how to proceed given the fact that we felt uncertain about the usefulness of our research and archival collection, we both agreed that trying to build something sooner might give us insight into the state of our research thus far.  One method of overcome hesitation to build/publish on my part was to channel the inner technical project/program manager bag of tricks I’ve collected with my professional experience over the last ten years.

The most influential software development practices theory over the last three decades are found under the Agile Development umbrella. As such, I found some strength to start building out the website for our archive in the  Manifesto for Agile Software Development. One value statement from that concise document I’ve always held close to me while working with software engineers is “working software over comprehensive documentation.” The principal behind this software cardinal virtue elaborated in the Principles behind the Agile Manifesto:
“working software is the primary measure of progress.” One important caveat to the values espoused in the Agile Manifesto, each of which is formulated with the favored value in the left, and the diminished value on the right, is that “while there is value in the items on
the right, we value the items on the left more.” One can assert that planning and documentation play a role in the development of a digital project in the context of digital humanities. Certainly it’s true when it comes to acquiring funding for a digital initiative. Still, a plan and documentation pale somewhat to having the digital project manifest itself, in this case, as a website. Consequently, I used the agile rationale to dive head first into creating a repo and generating some version of our archive on the web using Wax.

Another source of inspiration came in the form of software engineering management wisdom gleaned from the development of IBMs OS/360, the operation system developed for the company’s System/360 mainframe. Fred Brook’s The Mythical Man-Month details the learning he culled from his experience managing the OS/360, germinating from a question IBM’s CEO asked Brooks during his exit interview on why managing a software project seemed significantly difficult in comparison to a hardware project. While the book is clearly from a particular time and place in history, some of the lessons learned feel durable even in the face of increased processing power and more ergonomic/productive programming technologies. One chapter, “Plan to Throw One Away” felt appropriate to address any hesitation I might feel in starting our web archive as soon as possible. As Brooks sees it:

In most projects, the first system built is barely usable.There is no alternative but to start again, smarting but smarter, and build a redesigned version in which…problems are solved…one has to build a system to throw away, for even the best planning is not omniscient as to get it right the first time. The management question, there, is not whether to build a pilot system and throw it away. You will do that. The only question is whether to plan in advance to build a throwaway, or to promise to deliver the throwaway to customers…Hence plan to throw one away; you will, anyhow (Brooks, 116).

In an attempt to embrace this lesson, we’ve started to assemble our metadata in the csv without overthinking it, and knowing that we won’t get the filters and categorizations right the first time, but that in doing the work will yield the lessons for a reversion. Similarly, we’re dumping our entire photo catalog into the website as a first step. While some curation has already taken plan in the creation of our collection, we need to see all of the assets in one place to understand if any of them won’t work for our archive for one reason or another. I’ve also embraced the throwaway nature of some of the initial work in the naming conventions in our code: the collection at present is called temp_collection and we reuse templates from the Wax demo project as a starting off point. Even the repo name is wax-project, obviously is nondescript name. The key motivation is to get something working, even if we’ll eventually replace a great deal of it. Once we have a website up and running, we can critique it, file bugs and changes requests to it, and create a new version that better addresses our needs.

Citations

Brooks, Frederick Phillips. The Mythical Man-Month: Essays on Software Engineering. Addison-Wesley, 1995.

My thoughts on our semester-long project have been haunted by questions of sustainability after attending a skills lab hosted by CUNY’s Interactive Technology and Pedagogy (ITP) program a month ago on the subject as it relates to digital scholarship. Over the course of the workshop, Jesse Merandy, the first GC PhD candidate to complete a digital dissertation, elaborated on a central theme of what happens to digital projects in academia over time: they age, they falter, and, eventually, with changes in technologies and tools, they stop working. Beyond remarking on how a digital project will age and decade over time, Merandy also offered strategies to preserve the discovery generated by a digital academic project. In a nutshell, Jesse advocated for nth level documentation of research methods and thought processes (within the tolerances of sanity) that ideally takes place continuously throughout the project lifecycle.

While the tool selection decisions for our mainframe project attempted to counteract the speed at which digital work rots by way of statically generated content, markdown content, zero dollar hosting, and publicly available code repositories, we can’t escape the fact that eventually, our project will be hard to access as originally designed, if at all. To that end, Connie and I are focusing on how we can incorporate the process documentation to be present in or alongside our project website. Some of the subjects worth documenting and the rationale are found below

Reuse of our personal journal entry blogs

Reusing from our class commons site, to reflect what our week-to-week thoughts were about the progress, work methods, and moods about the project. We expect to do some reflection beyond our weekly journal entries will also be included, like topics for further discovery, or themes we weren’t able to address during the allotted time frame.

Narrating project challenges

Narrating the challenges we face during our time working on the project. One striking example is the difficulty in accessing physical archives for serendipitous findings. Another is encapsulating a doable topic within the time-allowing and supported by the archival material we were able to collect, both of which may not match any of the project proposal’s original themes or ideas.

Effect of time constraints

Detailing the scope and time titrations necessary to complete as coherent a project as possible. The original project imagined a staff of four to complete the resultant website. With two team members, multidisciplinary role assignments, and learning technology as well as subject matter compresses the origin “thick history” proposed before the project started. Of course, time constraints also help uncover new venues in which to explore, and conceive of novel studies. For instance, we’ve been a little surprised by how abstract and arty some of the advertisement creative turns out for what amounts to business equipment. We’re also exploring deformance and inspired collage as research methods into some of the themes we see in the cultural history of mainframe computers.

Identifying sources of inspiration

Identifying sources of inspiration for the project that aren’t constituent of the end product seems relevant for any future development. We can imagine a Zettelkasten style table for use in research down the line, as unused resources can emerge as relevant upon further research and analysis. We’ve been compiling research sources as well and inspirations from various forms of digital media .

Important side effect of documentation

One important side effect of documenting a digital humanities (DH) project from a bit of a remove: you are able to receive the cash value the enthusiasm on prototyping. That is to say, we can explicitly articulate weakness of the project output, without feeling like shortcomings are synonymous with project failure.

Kai Prenger graduated from Reed College in 2004 earning a BA in Literature, writing and defending a thesis called The Same But Different, an experiment applying the post-colonial theories of Homi K. Bhabha to 19th century American literature. His academic interests include misuse tools and theoretical frameworks on unexpected topics, using arbitrary process to transform subject matter (deformance)  and exploring areas deemed boring by a plurality of scholars. Previous work for pay includes dry cleaning, construction, social work, financial operations, product management, and data analysis and engineering. As a graduate student, he pursues play as productive strategy in scholarship. His main contributions to the project include development, theoretical and educational context, and shares project management duties with Connie, the co-project leader.