Reading with Zach Davis

Zach Davis

Zach Davis

Last week, calling Portland from the Digital Scholarship Lab at the Graduate Center, I had the pleasure of speaking with Manifold’s lead developer, Zach Davis at Cast Iron Coding. Yet again, my attempts to record the call came to naught, but I will conjure some of the conversation from my notes.

Zach is Principal Chief Technologist at Cast Iron Coding. His previous CIC projects include sites for the Hammer Museum in Los Angeles, The Edna McConnell Clark Foundation, the Jersey Give-Back Guide (check out the animation on the “generosity generator”) and Debates in Digital Humanities, a collaboration with The University of Minnesota Press and Matt Gold that served as a prototype for the Manifold project.

Zach has been working steadily and seems rejuvenated by the team’s recent Portland meeting. Talking through the next steps and considerations about how university presses will be able to customize Manifold installations seems to have crystallized the work that everyone has been doing in exciting ways.

First, I asked Zach what matters most to him about Manifold. He noted the two most important things to him at this stage, made even more clear after the meeting.

  1. That Manifold is open and open source. Zach says, “it is a pleasure to work on software that has to be open source, where it’s written into the very project.”
  2. That they are building something that solves a problem for a good number of people. He recognizes the audience, but beyond Manifold’s immediate uses for the press, the software has the potential to serve an even wider segment.

After that we spoke about ideal reading experiences. While his habits have changed since the days when he was a Ph.D. student in English at the CUNY Graduate Center, Zach says it’s “still a book most of the time. It depends on what kind of text. I don’t read theory and criticism the way I used to. For short forms, I will read on the web or my phone, but for reading, I still like the physical artifact.” We talked a bit about the different demands of different types of reading. When he was working on his dissertation, Zach categorized himself as a transcriber. He would cite passages as a way of thinking through the content. Now while working on Manifold, he imagines the sort of tools that would have facilitated this sort of reading. He says he also spent much of his academic life reading digital texts, which were often easier to track down. He thinks about the ways Manifold could simplify the lives of scholars.

What is he reading right now?

  1. A collection of Leonard Cohen poetry
  2. Margaret Atwood’s The Handmaid’s Tale

Both seem rather timely.

Lastly, I asked who inspires his work. Zach says lately he has been particularly inspired by the work of Dan Abramov, a JavaScript developer. He finds inspiration in Abramov’s career and particularly appreciates Abramov’s attitude about open source software and towards the community around his work. Now that he has transitioned to his developer role, he finds his book-world inspirations are much the same as they were ten years ago. He says he hopes he in any way resembles the thoughtful, careful, kind approach to work and students that he saw in Milton scholar and mentor Joseph Wittreich at the Graduate Center.

As the project moves on, I’m interested in the ways the underlying experience of the Manifold team influences the way they craft the reading experience.

Thanks, Zach!

Follow @zdavis

This Week in Manifold: Markdown and Backend Development

Since I last posted, we’ve been making development progress on a few different fronts. Much of this work is still in feature branches, and has yet to be merged into the main development branch. Therefore, I’m going to skip the full list of revisions in this post, and instead offer a high level description of our recent efforts.

Markdown and GitBook Support

Fundamentally, Manifold has been conceived as a tool for university presses. When it comes to thinking about how it will be used, UMNP has guided our thinking about what problems presses are trying to solve, and how Manifold can help. That said, I think everyone on the project has also been interested in the ways in which Manifold can be a useful tool for the broader academic community. At the very least, we want to make it possible for individuals to find ways to use Manifold. One impediment to this, in my mind, has been the fact that to date Manifold only accepts finished EPUB documents as an input format, and independent scholars and self-publishers may find it difficult to come up with finished EPUBs.

EPUBs are essentially packages containing HTML, CSS, and Javascript. In a sense, an EPUB is a small, self-contained website, and EPUB readers are offline, limited browsers. HTML, therefore, is already an input format that Manifold understands and can work with. What this means is that any document type that can easily be converted to HTML can likely be consumed by Manifold and made available to readers.

We refer to the process of slurping a book up into Manifold as “Ingestion.” Manifold can be extended by adding ingestion strategies to it. An ingestion strategy tells Manifold how to map a source document—eg, an EPUB—to a format it can understand. In short, we’ve anticipated that we’ll want to ingest other kinds of documents and have left places where other developers can create their own strategies. With the aim of testing out this approach and also furthering our goal of increasing Manifold’s user base, we spent a couple days writing a Markdown strategy that supports the GitBook format. This means that users will be able to feed Manifold a set of nested Markdown documents, which Manifold will then be able to make available online, just as it does an EPUB. Manifold’s documentation, for example, is authored following the GitBook format, and it can now be read within Manifold itself. Three cheers for eating our own dog food!

Backend Development

Since I last posted, we’ve also been hard at work at building out the backend interfaces. Most of the basic backend HTML and CSS has been completed, and we’re now in the process of developing reusable patterns and components in React to wire up the backend forms to the API. This has been challenging, as there is a lot of functionality required in Manifold’s admin interface, and figuring out how to model the requisite state while keeping in our Flux architecture has required some thinking. We’re close on this, with some initial proof of concept work, which I’ll be discussing more in subsequent posts.

That’s it for today! We’ll be posting more updates (hopefully with screenshots and some design comps) later this week.

 

 

This Week in Manifold: Team meeting, Numerous Fixes

This has been an exciting week for Manifold. The UMNP team—Terence, Dan, Susan, and Doug—and Matt all came out to Portland for one of our regular meetings. We met at the Cast Iron Coding office in the old Washington High School building and spent two days talking through issues, thinking about Manifold use cases, sorted through thorny metadata and DOI concerns, and generally reviewed how far we’ve come, where we’re at, and what’s left to do. I always find these meetings inspiring and invigorating, and am reminded of what a strong team we have in place for this project.

In the two weeks leading up to this meeting, the development and design team at Cast Iron has been working furiously to tighten up existing behavior and progress on the project resources. As a result, we don’t have a lot in the way of big new features to report for this sprint. We do, however, have a long list of fixes, small improvements, and tweaks, which I’m including below. Next week is a short week, and I likely won’t post an update until the following week. In the next sprint, we’ll be finalizing project resources, and then turning our attention back to the annotation user interface, and begin work on comment threads.

The release that went out to staging today includes the following revisions.

Backend

  • Add static markup/styles for backend text selector
  • Wire projects from API to backend views
  • Wire backend dashboard to project list
  • Add static upload form to backend
  • Add backend statics: maker select, textarea
  • Add radio group component to backend
  • Add static componet for backend panel/nav
  • Add static header to backend project detail
  • Add static component for backend activity
  • Add static for backend notifications
  • Add backend icons, secondary header style
  • Add static component for backend projects
  • Add placeholder avatar to makers

New Features

  • Add resource detail view
  • Slideshow loads resources one page at a time (batch loading)
  • Client can reduce one fetch to two locations in global state

UI Improvements

  • Close panels on click
  • Add graphic and messaging for users not following projects
  • Improve resource-related back links
  • Add marketing banner with signup button
  • Reduce input and button borders
  • Show actual annotation counts in text list
  • Refine resource handling on client
  • Animate project grid enter/leave (in some cases)
  • Improve following widget and project filtering
  • Mobilize mobile reader footer/appearance menu
  • Adjust reader header for mobile
  • Adjust positioning of user menu on mobile
  • Adjust resource collection icon on small sizes
  • Convert notification markup to use new styles
  • Add responsive font-styles to reader
  • Update twitter icon position on events

Bug fixes

  • Remove slide listeners on unmount
  • Correct resource detail link
  • Fix inconsistent text-header spacing
  • Adjust overlay header to match browse header
  • Fix svg grid padding on iOS
  • Prevent resource from showing blank slide
  • Fix resource link instances in card
  • Correct regression to collection detail
  • Remove underline from text title
  • Refactor resource scss files add dark overlay
  • Correct resource totals language
  • Show cards on collection resource list
  • Fix overlay on resource thumbnails
  • Fix slideshow transitions for demonstration
  • Prevent project subtitle wrapping on mobile
  • Fix text title weights on mobile
  • Restrict activity list on mobile
  • Fix sizing/wrapping on project metadata
  • Do not add resource to blank collection
  • Remove errant console.log message
  • Correct following transition style
  • Update user after edit profile
  • Correct home page header
  • Fix positioning and padding on header notifications
  • Scroll to top when changing sections
  • Correct annotation create
  • Adjust margin/positioning on thumbnails
  • Update primary nav for mobile
  • Fix duplicate project create events
  • Fix annotation popup position regression
  • Address improperly named project import method

API

  • Expose single collectionResource
  • Expose text age
  • Expose created month, day, and year on texts
  • Expose CollectionResources; add acts_as_list
  • Expose text annotation counts
  • Expose resource kinds on project
  • Move controllers to align with JSON API spec
  • Expose uncollected project resources in API
  • Expose user project favorites via API
  • Implement project subjects; adjust filtering
  • Ensure sources are associated with texts
  • Import resources when importing projects
  • Adjust resource serializers
  • Add collection controller to API
  • Generate resource thumbnail if it is an image
  • Expose date and kind data on collection
  • Expose project association counts
  • Add resource importer; build resource models
  • DRY up attachment validation; organize models

Misc

  • Refactor authentication; improve API actions
  • Refine frontend resource components
  • Correct resource and collection migrations
  • Clean up initializers

 

Reading with Susan Doerr

While the seismic ruptures of the election have unsettled the ground beneath us, it feels necessary to continue working on projects that look beyond the next four years, that address the possibility of connecting people through ideas and through constructive debate. Last week, in the midst of national turmoil, I had the pleasure of interviewing Susan Doerr, University of Minnesota Press Assistant Director, Digital Publishing and Operations. During our phone call, I asked Susan a number of questions about her thoughts on reading and the Manifold platform.

I started by asking Susan what matters most to her about Manifold. She talked about the process of collaborating with the Manifold team on writing the grant proposal, and thinking about publishing books in the browser. Susan believes the real revolution of an epub or pdf ebook is the speed of distribution — instant access for a reader. Susan said, “ebook reading devices are siloed — a reader is stuck in an app or device.” What the Manifold team wanted to do was “break free from that constraint. Ebooks today are replications of print — active media that don’t do much more than the print edition of a book. And we wanted to do more.”

Publishing a book in the browser allows it to be dynamic — vs static. The more they thought about it, the more opportunity they saw for readers to follow a project as it evolve because Manifold can publish a project iteratively, that is, in pieces over time.

We could transform the process of how the author might publish. We started our work with definitions: What is a version? What is an iteration? What is a resource? We broke from the word “book” and moved to the broader term “project,” which we define as a work that is a combination of texts and resources.

Susan noted that other publishing tools offer these features — but Manifold also aims to “create an efficient workflow process available to be replicated by other publishers.”

Next I asked, what’s your ideal reading experience? This one took a moment. Susan said she had no single answer. It all depends on “What is it that you’re reading for? Why are you coming to the text?” For leisure reading, Susan reads paperbacks or on her ebook reader. Reading for work, though–she’s a note taker–means reading reading parts of a work over time and marking up a text. Her reading demands “different interactions depending on why I’m reading this text. Reading for information, you want the apparatus for notes and asking questions and linking to other pieces.” For her, when reading for escapism she wants to lose herself in the story. Manifold is not meant to serve all the reasons you read, rather “it is addressing something specific. It’s not meant to be a panacea of all publishing.” Susan went on,

Print is a funny thing — we’re used to it historically being the solution for sharing and distributing published work. The book object — front cover, open it and read, turn the page, is familiar, and that medium for a mode of expressing text and images to share information is really sophisticated — it evolved over hundreds of years. Manifold is a baby — we’re developing its first version. A book, the object, meets so many needs — and we’ve had years to adapt it to meet so many needs — it feels perfect, but it may just be familiar.

When asked what she is reading now, Susan described a reading practice that spans formats. The books she reads circle around subjects she never studied in school, such as medieval central Asia. She is currently reading Empires of the Silk Road, by Christopher Beckwith, after finishing The Lost Enlightenment by S. Frederick Starr and Amazons: Lives and Legends of Warrior Women across the Ancient World by Adrienne Mayor. She also listens to audiobooks of cultural histories while she paints; she just finished The Art of Rivalry by Sebastian Smee, which she found after enjoying In Montmartre: Picasso, Matisse and Modernism in Paris 1900-1910, by Susan Roe. On her ebook reader, she says she reads mostly fiction — recently N. K. Jemisin’s The Obelisk Gate.

For the last question — who inspires your work? — Susan had quite an inspiring list.

  • Other university presses. She mentioned frontrunner work of National Academies Press. She follows publishing evolution — how they are adapting practices, not just around issues of open access. She appreciates learning from what works for others and what doesn’t.
  • Librarians. She mentioned the conversations and collaborations of librarians and publishers at the Charleston Conference.
  • Authors. By watching and talking to authors on social media, she sees how they figure out how to self-publish and work with publishers.

Ultimately, she finds inspiration in the process of art making.

Art – the process of art-making, creating and making; manifesting ideas as a physical thing — into text, fiber — if you’re making an art object — I find that riveting — that process, seeing the evolution of ideas through a work of art. If I’m able to go read about the ideas behind the artist’s work it changes my engagement with the art. Music is the same — one day while listening to Miles Davis’s Kind of Blue while in line at the bank in my car — I pulled out the pamphlet in the CD case and read about how the album was recorded, their process. It changed how I hear the music!

Throughout our conversation, I heard Susan’s excitement about the work she does and an attention to the ways she works and thinks. Susan gave me some good book recommendations, and we had the chance to discuss our hopes for scholarly communication and monographs. She generously shared her own experience, yet made clear that what matters most to her is serving her audience. A reassuring commitment in an unsteady time.

Thank you, Susan! 

 

Follow Susan @susanmpls.

This Week in Manifold: DevOps, Infrastructure, and Social Activity

Thanks for joining me for another installation of “This Week in Manifold.”

First off, please accept my apologies for missing last week’s update. When last Friday rolled around, we had a number of updates ready to go out to our staging site. However, when it was time to deploy, we hit a few unexpected problems.

DevOps, Hosting Manifold, and Deployment

This release adds a new metadata field to projects. Because the exact metadata requirements are difficult to pin down and may change from press to press, we wanted a relatively flexible approach to storing project, text, and resource metadata. Back in the day, we might have used an EAV model for this, but there are many well-documented drawbacks to that model. Because Manifold uses PostgreSQL as its database backend, we have access to a variety of field types for storing arbitrary amounts of data. In the past, we’ve used HSTORE for storing key/value pairs, but in this case we wanted something more flexible that could store different data types (HSTORE stores strings, but we want to store integers, boolean values, strings, arrays, etc). Recent versions of PostgreSQL include the JSONB field type, which is exactly what we want in this case.

Alas, that meant that the October 28th release required some infrastructure updates. Sure, we could have shelled into the staging server and done a quick upgrade, but that’s not how we roll on this project. It’s really important to us that it be possible to easily provision hosts for Manifold, which means automating as much as possible. As Manifold grows, it relies on more and more services to run, which makes setting it up increasingly complex. With this release, Manifold needs all of the following configured on the server to run correctly:

  • Ruby 2.3 (for the API)
  • Node 4.5 or higher (for the client)
  • Postgres 9.4 or higher (for storage)
  • Redis (for queuing background jobs)
  • ImageMagick or GraphicsMagick (for resizing images)
  • Nginx or Apache (for serving the API and the Client)

Moreover, in addition to having all these requirements in place, the server also requires that a number of background processes are always running. As of right now, there are four custom services (excluding the webserver and the database server) that need to be running on the host: 1) manifold_api (Rails app served by Puma), 2) manifold_client (Node app), 3) manifold_scheduler (Ruby daemon), and 4) manifold_workers (Sidekiq). Keeping four services running on a server (or on multiple servers) is not without its complexities. If we run these on Ubuntu Trusty (v14), for example, we need Upstart scripts that manage the services. If we run Manifold on Ubuntu Xenial (v16), then we’re going to need Systemd scripts. If it runs on older versions of Centos or Redhat, then we’ll probably need some init.d scripts.

Running a complex app with separate parts is tricky. Internally at Cast Iron, we use puppet and foreman to manage these services. Needing to support Postgres 9.4 got us thinking about deploying Manifold to Ubuntu Xenial, which in turn led us to revisit our manifests. Once we went to Xenial, we had to rewrite our startup scripts for systemd, which in turn revealed problems with how we were storing secrets in the environment. In short, instead of spending the last week working on project resources and feature development, we spent it paying down some technical debt on the infrastructure side, and improving Manifold’s devOps and stability.

That’s done now, and we’re deploying Manifold to Xenial and fully managing its environment and all dependencies via Puppet. Revisiting this infrastructure has also given us an opportunity to reflect further on Manifold’s installation story and continue discussions about how we can make Manifold easy for other presses to adopt and install.

New Features

We did manage to slip a few important features into this week’s release. The full list is below, but there’s one in particular I want to highlight.

This release includes a scheduler that runs constantly in the background while Manifold is running. One of the things this scheduler does is trigger a background job for fetching tweets related to projects in Manifold. That job currently runs hourly.

Editors can use twitter search terms to describe what kind of tweets Manifold should pull in for a given project. This gives editors quite a bit of flexibility. For example, Manifold might watch the author’s twitter account for all tweets with a specific hash tag. Or, it might watch twitter in general for all tweets that include a given hashtag. Our tweet fetching service accepts multiple search terms, so it’s possible for a project to follow multiple accounts and hashtags.

These tweets show up on the project activity feed. Readers can browse through the historical activity for a project and see the events—texts being added, tweets about the project, new resources uploaded—that took place as the project became a published book (see screenshot, below). Our hope is that showing this activity helps make public the iterative aspects of authorship.

Project Activity

Well, that’s enough for today. I’ll be back next week with another update. Enjoy the weekend!

Refactoring

  • Display project “makers” (authors, editors, etc) on one line
  • Improve header/icon lockup on project detail component
  • Refactor ingestion resources into a new model that is distinct from project resources
  • Clean up API binstubs

Features and Improvements

  • Add JSONB metadata field to projects; adjust project import mechanism to include metadata
  • Expose project metadata in API
  • Render project metadata in the client
  • Incorporate Sidekiq for background job processing
  • Add the concept of model ownership in various places. Manifold will now track who creates a project.
  • See a system-level user for ownership purposes
  • First pass at project events subsystem including background event generation; create Event factory class
  • Expose project events via the API
  • Render project events in the “activity” component on the project detail view
  • Add job for queuing the fetching of project tweets
  • Add job for fetching project tweets
  • Add a background scheduler (Clockwork) for triggering recurring background jobs

Tooling and Libraries

  • Update Postgres requirement to 9.4 or 9.5 for JSONB
  • Adjust Travis CI build to use Yarn instead of NPM
  • Feed Travis build notifications to Slack
  • Numerous revisions to deployment configuration

Bug Fixes

  • PropType correction in EventList component
  • Address 1:N queries in the project controller
  • Correct text icon on project texts list
  • Fix padding on coverless project heroes
  • Adjust font size and padding on project makers

 

Joining Manifold

Happy Halloween!

My name is Jojo Karlin and I am an English doctoral student and Digital Fellow at the Graduate Center, CUNY. I’ve joined Manifold this fall to help get the word out about what the team has been up to, and I am excited to investigate the generative potential built into this iterative, collaborative platform. I love the ways Manifold seeks to enrich scholarly publication by building communities of researchers engaged in collective annotation and networked reading.

When friends and acquaintances unfamiliar with the field hear I work in “digital humanities,” they often react with anxieties about the death of print. Skeptical bibliophiles lament the impact of screens on humanity as they cite popular science articles about babies swiping pages of print books.  Yet I remain a stalwart defender of books in their many forms. I grew up in a house lined with books and have a categorical weakness for library book sales and department book swaps; I also depend on my computer and smartphone as part of my reading practice.

Books, even print-only, are not single-use — people come to them and at them from different angles and at different times. I believe that the many ways we read books should be simultaneously available and that ideas deserve the full range of available outlets and expression. What I particularly love about Manifold is the way it bridges print and digital forms, giving presses and authors the opportunity to benefit from affordances of both — utilizing digital features while reinforcing the value of print-based scholarship.

Since joining Manifold, I have begun to see how the team approaches the transformations of text in recent years, the influx (sometimes numbing inundation) of social media, and the existing endeavors of numerous presses to engage scholarship digitally. “Building Manifold” gives me a sense of Manifold’s dual purpose– platform construction and conceptual restructuring — and Zach’s updates describe incremental decisions of development. By taking pains to publicly share the process of creating the tool, the Manifold team participates in the kind of transparent teamwork that the tool itself proposes. I look forward to sharing my perspective as well.

In the coming months, I will help to surface some of the exciting progress that the team has been making. I will post updates about design, interviews with team members, and reflections on some of the trickier conceptual decisions. Even jumping in now, I have found the whole team — Susan, Zach, Matt, Doug, Terence, Naomi, everyone!– to be wonderfully welcoming and warm. I am looking forward to learning more, and I hope you will share in my excitement.

If you have questions about Manifold, sign up for our newsletter, follow/star/love our git repository, follow @ManifoldScholar on Twitter, and feel free to get in touch.

Thanks and be well,

Jojo

This Week in Manifold: Project Detail Improvements

Welcome to a new regular feature on the Building Manifold blog: “This Week in Manifold.” As we move toward a beta version of Manifold (scheduled for March, 2017), I’ll be releasing a Manifold build to our staging server every Friday afternoon. Each release will be accompanied by a blog post explaining what the development team accomplished in the sprint leading up to the release. This post comes a few days late. When the Internet broke last week, our ability to release builds from Github was impacted, which delayed things a bit. I expect we’ll be back on schedule this week, with our next build going out on Friday, October 28.

Nota Bene: Our staging instance of Manifold is currently on a private server. However, we’ll be opening it up to the public in a few weeks, as soon as we’re able to load an initial set of texts with open access rights onto the platform. Once that happens, it will be possible for readers of this blog to check out our weekly builds for themselves.

Our last development sprint focused on tightening up existing code, mainly around the project detail view. Notable changes included the following:

Refactoring

  • Refactored login overlay CSS for improved reusability
  • Refactored the authentication reducer
  • Significantly reorganized client frontend components for easier readability and reusability

Features and Improvements

  • Exposed “published” boolean attribute on Texts in the API
  • Stubbed markup and styles for the resource collection detail component
  • Stubbed markup and styles for the collection list component
  • Stubbed markup and styles for the resource list component
  • Improved client application exception handling
  • Upgraded React to 15.4.0-RC3
  • Implemented project importer that imports projects, texts, and resources from json manifest
  • Expanded project API to expose all data shown in the comps
  • Adjusted component to show project creator names below project thumbnails
  • Adjusted component to show actual project dates below project thumbnails
  • Stubbed markup and styles for project events (on project detail, and stand-alone), aka activity
  • Added mobile styles for event lists
  • Added metadata JSONB field type to projects and expose via API
  • Implemented actual project metadata in the project detail component

Tooling and Libraries

  • Switched Manifold client testing framework to Jest
  • Updated all client NPM modules
  • DRY’d up client application Webpack configuration
  • Reorganized and improved build and server scripts for client application
  • Improved API application Puma configuration
  • Switched client from NPM to Yarn for deterministic dependency resolution (and speed)
  • Removed redux-devtools component; replace with similar Chrome extension
  • Added moment module for handling dates and times
  • Updated global and API Rubies to version 2.3.1

Bug Fixes

  • Corrected login overlay view state
  • Removed randomness from stubbed resource components (breaks universal rendering)
  • Added code to prevent client application from requesting “page” entities on every route change

In addition to these changes, the Manifold team also touched base last week during our recurring (bi-monthly) meeting. The group discussed text and project metadata requirements, the overall project roadmap, the agenda for our in-person Portland meeting in mid-November, among other things. Joining that call for the first time was JoJo Karlin, a Doctoral student in English at the CUNY Graduate Center who is working with Matt Gold on this project. You’ll be hearing more from JoJo in the coming weeks as she works to share Manifold updates and progress via this blog.

This week’s development sprint will be focused on a few main goals. Naomi will be finishing up markup and UX for the resource collection slideshow. Zach will be focused on the initial modeling of project resources and project resource collections in the API, and wiring that data up to the client. He’ll also be improving the project importer—delivered in last week’s release—to pull in sample resources for our demonstration projects and texts.

All work and no play makes for dull developers, and so I will leave you with a screenshot of Manifold’s new error screen (only visible in development mode), inspired by the first computer Zach ever owned, the illustrious Commodore 64.

screen-shot-2016-10-24-at-6-33-08-am

 

Starting Points with the Manifold Digital Projects Editor

As Jason indicated in this space earlier, Manifold is not simply an endeavor to create a better publishing platform; it is an answer to the challenge of rethinking and reframing the concept of scholarly publishing. In broad strokes, scholarly publishing is very much still a print-centric enterprise. Despite the vast libraries of electronic publications available, the systems, mindsets, and expectations of the greater university press culture—including those of authors and the academy—are engineered specifically for print.

In terms of production, while many presses have augmented their procedures over the past two decades, those alterations tend to simply mirror print methods instead of refashioning them to account for digital materials and platforms. For other presses, third-party service providers, or packagers, handle the creation of electronic editions in parallel with print or as an afterthought to it. That is to say, even when print isn’t to be the only medium of publication, it still receives primacy over all other editions. When a question of formatting comes up, it’s a question to be resolved for print first. When internal elements are being scrutinized, they are done through a lens that foremost anticipates a static physical object.

We’ve reached a moment, however, when we need to step back from print and see it in the proper context among the myriad means of expression scholars now have at their disposal. And it’s time to grapple with the fact that scholarly publishing involves more than books, more than journals, more than print. It’s not tied to paper; it’s not a function of the software it passes through. Instead, it’s the expression of content in the most meaningful and impactful ways possible. In that context, university presses must become adaptive and able to treat materials that aren’t always easily categorized or codified just as well as they do traditional vehicles like a journal or monograph.

That is no small thing. The print paradigm has been refined and honed for generations. It is deeply ingrained, predicating the workings of every department within a press. Reengineering it is not something that will happen overnight. Nor should it. But nor should we let the print mold stand as a boulder, cordoning off those modes of expression that weren’t possible a few years ago or those just over the horizon.

Exploring those opportunities is the commitment of the Manifold team. We bring together the perspectives of the university press, the scholar, and the technologist to hone in on new ways presses can present scholarship, realistically adapt existing procedures to account for a broad spectrum of publishing output, and technically deliver those varied means of expression to the readership in ways they are expecting as well as in ways they are not.

As the Manifold digital projects editor, I am working closely with the platform developers at Cast Iron Coding, our partners at the GC Digital Scholarship Lab, authors, and press staff across departments here at Minnesota to help craft, test, and document replicable processes that will allow presses to shift from a publishing plan with a very specific terminus to one that celebrates projects as a spectrum of scholarly publication. In the weeks and months ahead, I’ll be returning here to talk more about the implications of that and the challenges we’re working through as we move from platform wireframes into more robust test cases.

Stay tuned. The fun is just starting!

—Terence Smyre, Manifold Digital Projects Editor

Thoughts from Editors and Authors on What Makes a Good Manifold Project

As Manifold Scholarship progresses through its first rounds of wireframes, editors at the University of Minnesota Press are already discussing the platform with authors and considering book projects. Manifold will have an impact on the full span of a project, from the early stages of researching and collecting data for a book, to the drafting of a proposal, to peer review and press evaluation, and across the iterative stages of a manuscript’s organic development leading to the peer reviewed, published edition. Just as Manifold is designed to transform the nature of scholarly publishing, we are also asking scholars, from their earliest articulations, to think elastically about the ways in which Manifold can expand their project beyond the static, physical book.

As I’ve been asking editors and press authors to describe what makes a project suitable for publication on Manifold, I’ve found myself reflecting on the limitations the traditional print book can impose on scholars.

One could argue that the traditional print scholarly monograph isn’t an accurate record of a research project. The fixed form of the book, for example, doesn’t reflect the long duration of research, the months of ethnography, the full compliment of data collection and archival deep-dives. The monograph doesn’t record the full chorus of voices that help shape a project, such as the feedback of colleagues and peers. Research is already iterative, benefitting from community dialogue and from interfacing with an array of media. It’s just that the current way of disseminating that research doesn’t reflect those pre-publication engagements.

Up to now, when authors have wanted to share with readers materials that can’t fit into a print book such as audio and video files, teaching tools, or archival materials, they have often had to host them on a disconnected website. There’s often little travel between the website and the physical book, and these websites quickly fade away, disconnected by link rot or taken down from university servers when a scholar switches institutions. But these objects are never ancillary—they are part and parcel of the work itself. One potential Manifold author remarked to me that the traditional book doesn’t offer readers the chance to review the primary materials and say, “I disagree.” Manifold will allow authors to embed these objects within or alongside the text so that readers can chart their own course through all the elements that make up a scholarly book and research project.

This feature is especially important to Manifold author Mara Mills, assistant professor of media, culture and communication at New York University. Mills was initially attracted to Manifold because it provided an opportunity to develop an accessible multimedia publication:

My manuscript-in-progress,“Print Disability and New Reading Formats,” examines the century-long history of electronic reading by those excluded from the inkprint book. The research for this project has involved the digital transfer of hundreds of historical sound recordings: shellac Talking Book records; open reel tapes of early text-to-tone and text-to-speech reading machine output; demonstration cassettes of early time stretching technology for “speed listening”; recordings of audio-described films and graphic novels. My book, about multimodal reading and the multiplicity of “the book,” simply cannot exist in inkprint format alone.

Often, authors finish a book project that distills hours of audio interviews into a handful of block quotes, or a gallery of scanned images from which they draw fifteen or twenty to produce in black and white on the printed page. The traditional monograph doesn’t always account for the labor of discovery and archiving that is a part of research. When copyright and ethics allow, authors will be able to share these archives with readers through Manifold.

Stephanie Boluk and Patrick Lemieux are currently authoring their first book, tentatively titled “Metgaming: Videogames and the Practice of Play,” which studies a critical practice and form of game design philosophy in which playing games, making games, and thinking about games occur simultaneously. The Manifold edition of their book will include original, playable games designed by the authors, but they also see the Manifold project as archiving a genre of media which is often elusive:

Given the kinds of practice-based research both documented and performed in the volume, we’re very excited to begin “Metagaming” with the Manifold team. Manifold not only offers the possibility to hyperlink to sources outside the text, replace figures with HD video, and embed our original games directly within the text, but could also function as a repository or archive for unique and hard-to-find software discussed and used throughout the book. We also hope Manifold will help to make “Metagaming” more accessible for students by offering additional educational resources like a podcast we are in the process of planning in which we interview metagamers featured in the chapters and 20-min video summaries discussing the content of each chapter.

This willingness to think beyond the book is what acquisitions editors are looking for in Manifold projects. Press director and acquiring editor Doug Armato explains:

With Manifold, I’m looking for publishing projects that can’t be fully realized in the fixed, single-dimension of the page. This is not just a matter of adding multi-media or live links, but of seeing a scholarly work in its context of a longer research project, making its archive visible and accessible, and enabling the reader feedback and discussion that shape a book’s creation and reception. Not every scholarly author will want to work this way, but some do and I want Manifold to provide a publishing home for them—and one they don’t have to build themselves, as with the authoring tools already out there.

We are developing Manifold to not only expand what can be included within the book, but also to break down the temporal barriers that separate years of research from the book’s publication for authors who want to engage their readers at an early stage, share drafts of chapters in order to try out ideas, and receive feedback and dialogue as a form of open peer review. Danielle Kasprzak is Humanities Editor at the press and also acquires and oversees the press’s Forerunners: Ideas First program, which publishes thoughts-in-process as digital works and as affordable print publications. Forerunners aims to collapse the current publishing timeline to twelve weeks, so timing is often on her mind. Kasprzak is most excited about getting ideas out into the world more quickly than the traditional publication schedules of print books:

Part of the reason why authors are attracted to Forerunners is the speed at which texts are released. I’m pleased that scholars from diverse disciplines have seen publishing their ideas in a speculative, early way as beneficial to their thinking process.

Mara Mills is also excited by the pre-publication aspects we are building into Manifold. For Mills, this pre-publication aspect of Manifold will be “a way to curate my sound materials, write a few introductory provocations, and invite others to think with me about what it means to read.”

This notion of curation is critical to what I am looking for in a Manifold book project. Manifold will track a work as it is conceptualized, researched, written, and read, giving readers access to primary research documents and data, links to related archives, rich media, social media, and reading tools. Taking advantage of these tools, an author will also become a curator, shaping archives, providing context for readers, and illustrating the varied parts that make up her book and larger research project. It will ask authors to collaborate with the press on questions of copyright and ethics, peer review and evaluation, and to consider how best to connect with readers (both within the academy and general readers) in meaningful ways.

Manifold will recode the very definition of the scholarly monograph. To realize that goal, we are looking for authors whose vision for their scholarly projects extends beyond the limitations of the traditional book.

— Jason Weidemann, Editorial Director

A Technical Introduction to Manifold

Hello Manifoldians!

I’m Zach Davis, principle at Cast Iron Coding, a web development studio in Portland, Oregon. My team and I are responsible for UX design, visual design, and development of Manifold over the course of the grant, and it is my hope that I’ll be able to post regular updates here detailing development and design decisions, challenges, and milestones over the course of the project.

For now, however, I’d like to walk through the technology stack we’ve settled on, and the reasoning behind some of these choices. If anyone has any questions, please don’t hesitate to post a comment!

Where to find the source code

As you know, one of the requirements of the grant funding this development is that Manifold be released as open source, and our current plan is to release Manifold under the GPLv3. For the time being, Manifold source code is stored in the ManifoldScholar/manifold Github repository. If you look at the ManifoldScholar GitHub organization, you’ll see additional repositories for Manifold-API and Manifold-Client. Eventually, we hope to be able to provide the Manifold API as a stand-alone piece of software that can be used to parse, store, and expose ePub and Markdown documents over a RESTful API. In preparation for this, we’re using a git subtree-split strategy to break the Manifold project into separate API and Client packages. These split repositories are updated significantly less frequently than the main Manifold repository. If your goal is to follow our development, for now your best bet will be to just watch the primary repository.

We’ve already made significant progress on Manifold, although we’re still far from an alpha release. We’d love it if you’d show your support for our project by starring our GitHub repo and keeping an eye on development. As we get closer to a stable alpha release in 2016, we’ll invite community members to download and install their own instance of Manifold.

Server-side architecture

Manifold is split into the client application, and the server-side application. For now, these two applications share a repository to simplify development, but they are very distinct and meant to run independently of each other.

The server-side application is built in Ruby and Rails. Specifically, we’re using what is currently edge Rails, and what will soon be Rails 5. The development team thought long and hard about what server-side language to use, which was mainly a debate about the relative merits of using Ruby or Javascript on the server. While we have many years of experience working with PHP, and understand that it is still a popular, easy choice among academic developers, we felt strongly that the advantages of Ruby—strong OOP support, support for more functional styles, cleaner and more consistent syntax, and the maturity of Rails—outweighed the disadvantages of a more complex execution model and smaller (but by no means small) developer community. Laravel, the current leading PHP framework, for all its notable strengths, lacks the completeness and maturity of Rails and Active Record. Our choice to go with edge rails, rather than stable Rails 4.x, was driven by the fact that our server-side component is only serving an API, and Rails 5 will eventually ship with an api-only flag. This means that many aspects of Rails—the view layer, sprockets, etc—have been removed, making for a more lightweight framework overall. Another strong reason for choosing Rails was the presence of a strong HTML/XML parsing library in Nokogiri. Manifold deals heavily (but not exclusively) in EPUBs, which are HTML documents. To pull those documents apart and recreate them in the browser, we need a powerful parsing tool, which we’ve found in Nokogiri.

The server side application exposes a REST style API to be consumed by the client. This API conforms to the style and conventions laid out by Steve Klabnik, Yehuda Katz, Dan Gebhardt, Tyler Kellen, and Ethan Resnick in the JSON API Specification. While it’s important that developers expose all the things with APIs, it’s challenging when each API follows its own idiosyncratic conventions. One of our goals on this project is to make Manifold as easy as possible to integrate into a presses existing infrastructure and environment, and following an established API specification helps us with that goal. Because the Manifold client application consumed Manifold’s public API, integrators can be sure that the API is well tested and reliable.

Authentication against the API will be handled using JSON Web Tokens (JWT). It will also be possible for a user to generate an API token by logging in through an OAuth provider such as Twitter or Facebook.

Client-side architecture

If we made a safe, conservative choice in Rails on the server-side, we’ve taken more of a leap on the client-side. The Manifold client is a single page application (SPA) that is built on React and Redux. Both are relatively new Javascript libraries (or frameworks, depending on how you look at things) that are rapidly gaining mindshare and popularity among front-end developers. For those who are unfamiliar, React is a Javascript library that simplifies the process of creating reusable components. Unlike other popular libraries such as Angular or Knockout, React does not attempt to solve the problem of two-way data binding. Instead, it is meant to be used with a specific architecture called Flux, which is structured around one-way data flow and immutability. Both React and Redux have a relatively small surface area. Redux APIs are small, and the library as a whole is under 15k.

At Cast Iron, we’ve worked with many Javascript frameworks, in particular Angular and Backbone. Over time, client-side development has become quite complex, and it’s our feeling that while Angular can work well on some projects, it doesn’t do enough to reduce that complexity. By restricting the way in which data can flow through the application, and abstracting away the asynchronicity that can make client-side development challenging, we’ve found Redux and React to be a powerful combination that allows us to iterate quickly without sacrificing quality or maintainability.

There are some challenges that come with developing a single page javascript application. For our purposes, the biggest challenge is to ensure that there is content loaded on the page before the javascript executes. We feel strongly that Manifold needs to be accessible to users with disability, to search engine crawlers, to screen readers, etc, and that we can’t count on a javascript environment. For this reason, the Manifold client will be served by a small Node/Express application running on the server. Most of the javascript that executes in the browser is built to be isomorphic (now also known as universal), which means that care has been taken to ensure that it can be executed in a server-side context (node) and in a client-side context (the browser). The practical outcome of this approach is that the server-side component will be able to fully render the HTML before sending the page to the client, which solves the many accessibility and SEO problems.

The advantages to the SPA approach are, well, manifold. The application will feel very fast, and we’ll be vastly reducing the amount of data that’s sent over the network. Complex UI elements, like the annotation pieces, will be have a much more stable, testable framework backing them. There will be more room for reusable components, and the various state-changes that can occur in the client-side application will be well tested.

While we’re diving in head-first on React + Redux, we are not, for now, following the current trend of doing only inline-CSS. For the time being, we’ll be using the SASS preprocessor for all styles.

At the language level, we’re relying heavily on ES6 and upcoming ES7 features. We’re using Babel to transpile ES6+ code down to ES5  so that it will run in IE9+, Firefox, and Safari. By using edge Javascript language features, our hope is that to some degree we will future proof Manifold code. For now, we’re limiting ourselves to ES6+ features that are at stage 1 or greater, and acknowledge that there is some risk even with stage 1.

We rely heavily on NPM for package management, and Webpack for transpiling assets during development, and for building assets for production. At Cast Iron, we’ve used Grunt and Gulp on other projects, but it looks to us like the React community is gravitating toward Webpack, and for good reasons. On Manifold, it’s being used for automatically linting our code, for generating icon fonts from SVG icons, for transpiling ES6+ to ES5, and Sass to CSS.

Testing

Tests are important. They build confidence and help us to refactor without regressions. While we don’t always follow test-driven-development practices, we do feel that it’s important to have a robust test suite in place. On the API side, we’re using rspec for tests. On the client-side we will be using Mocha.

Server infrastructure and continuous integration

DevOps and infrastructure automation are essential to our workflow at Cast Iron. We use Boxen to setup development instances of projects, and we use Puppet to deploy applications to staging and production environments. Our manifests for deploying Manifold are still in progress, but they’re close. Soon, I hope to have a staging environment that’s updated regularly via Jenkins, our continuous integration server. Soon, we’ll also have Travis build notifications in place on the Github repository.

To run Manifold, you’ll need to have the following setup on a server:

  • Nginx for serving the Ruby app and the Node app
  • Puma for serving Manifold API (although you could use Unicorn or another app server)
  • Ruby 2.2.x
  • Postgres for the API database
  • A recent version of Node
  • Eventually, I expect you’ll need Elastic Search for the search component

We’ll be providing instructions on how to set this up, as well as sample config files. Eventually, I hope to provide apt-get packages for Ubuntu as well. Once things are a bit more stable, we’ll regularly release docker containers that you can use to take Manifold for a spin.

In Closing

Hopefully this gives you a better sense of what we’re using to build Manifold, and why. I’d love to have a conversation about our choices, so please don’t hesitate to leave feedback in the comments. In the coming weeks, I’m going to try to share some early artifacts from the UX and visual design process, to give you a better sense of what Manifold will look like and what it will be capable of.