New and Improved

About this time last year, I began working on the Technical Guidelines for authors whose work we had accepted for publication. Completed in June, these guidelines were then posted on our website so current authors, as well as any prospective authors who might be interested, could view them. As expected, we’ve been learning a lot as we’ve progressed through the process of not just acquisition and production but also of archiving the projects we’re publishing, so it’s logical that over time we adapt our strategies. And as we adapt, we must update our recommendations and requirements to keep in pace with the ever-changing technologies authors want to leverage.

Our latest update has been to the Documentation Guidelines. I originally highlighted the first version of these guidelines in “Capturing the Ephemeral.” Today, visitors to our site will find a much more specific set of requirements aimed at generating a document that can sit at the top of a project’s repository archive. And this particular version of the archive, just one of a few we hope to implement, is meant to be a longterm record of the work for future researchers who might not have access to a web browser or an interface that can provide the original experience of viewing and navigating the project as it was initially published. The repository archive ensures that the content and code files remain part of the scholarly record even if the tools for delivering them evolve far beyond what we can imagine right now. And a thorough documentation can serve as a kind of blueprint or guide to the files contained in the archive.

Documentation is a good idea for any creator of digital work, and hopefully our recommendations will be helpful for anyone working in digital formats.

Documentation is always a good idea when you create digital work, but what should be documented exactly? While the initial version of the guidelines suggested authors choose what they would want others to know about the project, and encouraged them to put that information within the project itself, the new guidelines list specific properties of the project that need to be documented, outline how to organize and communicate those properties, and  require the documentation actually be a separate file that exists outside of the project itself. After all, if a web project is no longer accessible, any documentation that exists within that framework will also be difficult to access.

You can read the details in the guidelines themselves, but essentially, the new version asks authors to provide a.) a brief summary of the project’s purpose and scope; b.) technical requirements; c.) technical specs and libraries; d.) a detailed and illustrated description (text as well as screencast) of the project’s interface and navigation; e.) a blueprint of the file/media/content relationships; and f.) unformatted and consolidated bibliography and credits.

While we continue exploring innovative solutions for preserving the full experience of a web-based scholarly work, we must at the very least ensure that the contents and code persist in a safe space. But such a space flattens a project, and the only way to provide future researchers an idea of how all that content and code looked when it was processed and rendered in today’s web environments is to include detailed documentation. It’s a good idea for any creator of digital work, and hopefully our recommendations will be helpful for anyone working in digital formats.