Originally published: 02-18-2019 | Beta release update: 04-02-2019
As we roll through (and beyond!) the beta release, our documentation is expanding, just as we planned below. Drafting test cases and protocols for the nodes led to a swift expansion of the EaaSI User Handbook, which you can check out to learn more about how EaaSI users navigate and interact with software. The installation section and the discussions on our EaaSI Tech Talk forum can also give some insight into the ins and outs of managed Docker deployment! It’s all part of the plan: docs by the network, for the community!
As Euan wrote recently in his project overview, the EaaSI team has already accomplished a lot in the past year and a half and has a lot more yet ahead. With the beta release of the EaaSI platform to our partner Node Hosts swiftly approaching, the team is hard at work prepping a strong network launch: squashing bugs, wrangling metadata, cracking open vintage software like a fine wine.
….but how would you know about any of that? Unless we showed you?
It’s right there in our program description: “The EaaSI program of work is focused on the development of technology and services that support distributed management, documentation, sharing, and use of emulated software across a broad range of disciplines.”
Creating open, shareable resources has been a personal crusade of mine in my time as an audiovisual and digital preservationist (the students I worked with at NYU got this lecture from me a lot). I firmly believe that exposing our professional practices to each other, no matter what form you do it in, only makes the community collectively stronger, smarter, savvier. Coming on board the team last October, I was thrilled that the EaaSI staff shared my desire to put together a firm plan for creating accessible documentation of our work.
Crafting not just individual pieces of documentation, but a documentation strategy, required considering two major factors:
- What exactly are we going to make?
- Who is it intended for?
What kinds of documentation will we produce?
- Technical documentation: EaaSI isn’t just a software stack, but our EaaS platform is a big part of the program. We’re customizing EaaS for the network’s needs, so users will need to know where to go, what to click, and how to fix it when something goes awry. To that end, we need installation and deployment guidelines, a user guide, and an issue tracking platform to communicate bugs to our development team ASAP.
- Tools & Exercises: We’re constantly looking for feedback from our node teams on their practices and philosophy regarding software preservation and curation – our structured and semi-structured exercises provoke thought and build capacity in the EaaSI network, and might at your organization as well. We’ll also be making more hands-on workshop-style activities to guide EaaSI participants and onlookers through the more complex details of our work.
- Workflows: As staff and Node Hosts figure out how EaaSI fits into existing digital preservation and access workflows, you know we’re all going to have to write it down. Wouldn’t want to forget!
- Project updates and news posts: There’s a lot to sift through in our program of work. Breaking it all down in a narrative voice can make our concepts more accessible. Plus, sometimes we’re going to have exciting discoveries and developments that we know you’ll want to share with others!
- Presentations: You’ll probably be seeing at least one EaaSI staff member at a conference near you this year. But for those who can’t make it in person: we know slide decks aren’t a replacement for the real deal, but please take them as a token of our affection!
- Conversation! Rachel Mattson gave a talk at the Association of Moving Image Archivists conference in 2016 titled “Conversation Is My Favorite Tech Tool”. Truer words were never spoken. I’ve personally learned as much from listservs, forums and interviews over the years as I have from more formally structured kinds of documentation. The debates, experience, and advice we discover from each other within the network are going to be invaluable records in and of themselves.
What audiences need access to our documentation?
- EaaSI staff: Look, I know I said all documentation should be open, but realistically we still make a lot of stuff that isn’t ready for prime time. But G Suite, Slack, and private git repositories will continue to do fine while we touch things up.
- EaaSI Node teams: A decentralized network is only going to work if we talk to each other a lot. And sometimes those details are going to have to stay between us, especially when network security, authentication, and fair use are concerned.
- Software preservationists, digital curators and scholars, reproducibility advocates, history buffs and beyond: SPN knows: communities of practice are important.
So what did we come up with? Where can you find anything and everything EaaSI-ly?
- This web site!: If you’re already here….mission accomplished! Our biggest priority was that no matter where we branched out, there would be a one-stop shop to explore all corners of EaaSI. Our SPN project site is intended to be a portal, where you can access not just this blog, but training materials, conference slideshows, materials generated by our fabulous node partners, and more. And we’ll always be sure to link and guide out to whatever other platforms we use, like….
- GitLab: From a development operations standpoint, GitLab had everything we needed: version and access control for our software repositories, baked-in features for automated deployment and project management, a built-in issue/bug tracker, etc. We can even host our technical documentation via GitLab Pages, using our dev team’s preferred markup generator: Python-based static Sphinx sites written in reStructuredText, in a practical, readable theme created by the Read the Docs project
- Google Groups: It might be a little while before we can get an emulated EaaSI network of Usenet circa 1980 up and running, but forum-style Google Groups are *just* nostalgic enough to do the trick (and practical to boot).
As the network grows, so may our nested threads – but for now, in addition to an internal network general discussion Group, we manage a community “EaaSI Tech Talk” group for open conversation on workflows, best practices, design improvements, emulation features and hopefully more.