We are excited to announce the release of the Rockefeller Archive Center Documentation Website, a central platform for storing and sharing our institutional policies, workflows, guides, and other forms of documentation! We also want our site to generate more critical thought about how and why we write documentation, especially in terms of how we manage revisions to content, what formatting decisions we make in order to provide meaningful structure, and how we can use our documentation to contribute to the larger archives community. As a well-resourced institution, we feel a professional responsibility to be transparent about the tools and procedures we develop that may benefit our fellow archivists.
What It Is
The website facilitates easy discovery of documentation for RAC staff members, and also enables other archivists and professionals in related fields to use our documentation as resource and reference material when establishing or amending their own policies and procedures. Because all content published on the site is assigned a Creative Commons Zero (CC0) license, you don’t need to ask our permission to copy, modify, or share any of the documentation. In fact, we strongly encourage you to use our documentation in any way that helps you meet your needs or achieve your institution’s goals!
We use Jekyll - a static site generator - to structure, style, and deploy our site. Individual documentation files are first converted into Markdown by RAC staff members, and then they are uploaded to separate repositories under the RAC GitHub organization. We hope that, in addition to using and adapting the documentation we make available on the site, other archivists also take inspiration from the website’s structure and design when trying to find solutions for storing and sharing their institution’s documentation. You can access the code that builds docs.rockarch.org on the RAC GitHub page!
Why We Built It
When developing the website, we wanted to provide a single location where our colleagues could quickly find and access documentation. The site will replace the complicated and inconsistent filing structure we currently use on our institution’s shared drive for storing documentation. Staff members will no longer have to search or remember complex hierarchies of folders in order to try and find a specific policy or guide. The site’s flat structure is also friendly to outside users who are completely unfamiliar with the filing conventions employed on our shared drive. Although we initially considered organizing the documentation on the site under our institution’s different function areas, we quickly realized that such an organizational scheme would prove inhibiting and frustrating when most of our documentation is cross-functional in nature.
Furthermore, by using a version control tool like GitHub to host and manage the site’s content, we are providing a single location where staff members can edit documentation and disseminate revised content. This eliminates the process of creating a new version of a file every time there is an update to a particular policy. The accumulation of outdated files in different folders on the shared drive currently exacerbates the difficulties that staff members encounter when trying to track down the documentation they need. Writing from personal experience, I remember that when I first started working at the RAC, I used an old policy for guidance on certain processing procedures for several weeks because I did not realize it was out of date. Now, we will simply edit the proper Markdown files on GitHub in order to incorporate revisions to our documentation. The most up-to-date versions of our policies and guides will always be available on the site.
The idea of building a website to store our institution’s documentation excited us for reasons beyond the benefits of web access and version control. We were also eager to use web conventions to enhance our documentation.
Efficient navigation is an especially useful feature for documentation because most people do not want to read the complete text of a manual or even a policy. We want to quickly find the content that will explain how to perform a certain procedure or how to comply with a stipulation in a policy. The Markdown format we use to manage our documentation on GitHub allows us to embed links that can bring users directly to specific passages within our documentation or to external content such as established standards and practices, additional resources, and consulted examples. Although, we could create those links within a Word document, links are an integral part of how the internet works, so a website is better suited to deploy them. Our site also provides side navigation for movement between the different segments of a piece of documentation.
Taking a step back from the features facilitated by pushing our content to the web, I want to highlight our project’s goal to promote the creation of well-structured documentation that lends itself to enhancement by a markup language like Markdown. Features like the side navigation are impossible to implement if the documentation is not meaningfully structured. When completing our initial conversions of documentation in Word Documents to Markdown, we soon observed the differences between styling a piece of documentation and structuring one. As part of our efforts to involve more of our colleagues in moving greater quantities of RAC documentation to the site, we try to emphasize the larger learning objective of discovering how to make intentional and meaningful structure decisions. These decisions largely concern how to define a document’s individual components with headings, how to use varying levels of headings to express the relationships between the different components and their subcomponents, and how to determine when it is is appropriate to use ordered or unordered lists to represent sets of information.
Lastly, as mentioned earlier in this blog post, we want to use the site to share our documentation with other archives professionals. Our staff members took inspiration from outside resources when drafting our institutional documentation, and we want to carry on that tradition of collaboration. Rather than try to find a place on the RAC official website where we could stash all of our policies and guides or try to publish each documentation item separately on the web, we opted for a central location where documentation is explicitly licensed, so that users know what they can and cannot do with the content. We want our site to appear inviting to non-RAC users, and we want it to clearly communicate that none of the content shared on it is copyrighted.
In cases where a piece of documentation contains sensitive information that we cannot publicly release the item can be tagged for internal-only access. Staff members using our institution’s network will have full access to the documentation, but users accessing our site from outside our network will not be able to view the documentation. This feature permits us to still store all of our documentation in one place without releasing information that should not be made public.
How We Did It
Last summer, RAC Processing Assistant Director Bob Battaly and Digital Programs Assistant Director Hillel Arnold approached me and my colleagues, Katie Martin and Hannah Sistrunk, to collaborate on a project to put the RAC Guide to Processing Collections online for staff and external user access. The three of us were recent hires at the RAC, and our ADs set up the project in order to give us an opportunity to work as a team and to collaborate across departments (Katie and I are on the processing team and Hannah is on the digital programs team). Teamwork certainly proved to be a critical component of our project because of our use of GitHub to build a repository to house the content for the processing manual site. We learned to use GitHub repo branches to edit content and submit changes to our team’s work as well as to review and accept our teammates’ changes. However, before we could put the processing manual onto our GitHub repo, we first had to convert it into Markdown. The extensive length of the processing manual allowed us to become fairly skilled at formatting content within Markdown and utilizing headings to structure content.
We were proud when we finished creating the website for the RAC’s processing manual, and we were excited when that site became a proof-of-concept model for a more ambitious platform that would host all of our organization’s documentation. Under Hillel’s leadership, we developed a strategy to deploy the content we had in the Markdown files for the processing manual under a cohesive theme that could be extended to other documentation items. This theme would provide a uniform structure and style for the different pieces of documentation, and it would create a homepage for access to all of the documentation hosted on the platform. We had to learn to use the Liquid template language, Bootstrap CSS, and a little JavaScript to properly design the Jekyll-themed layouts for the our site’s homepage and individual documentation. By utilizing a Python script in combination with Jekyll, we can automate updates to the site, allowing our colleagues to devote their time towards adding and editing the documentation content rather than updating a website.
With the website now complete and the processing manual fully accessible, we have switched focus to putting more RAC documentation on the site and to training our colleagues on how to migrate this content. During the last couple of months, we drafted a guide to teach people how to add and manage content on the site, and we organized a workshop to introduce our fellow staff members to Markdown. Our team has found this phase of the project particularly rewarding because it has allowed us to reflect on all of the skills we have developed for the purpose of educating others, to implement our understandings of well-structured documentation into the creation of our own guide, and to include others in the processes that will make up the RAC’s new workflow for creating, distributing, and revising institutional documentation.
Throughout the entire length of our project, our team has been incredibly fortunate to receive the enthusiasm and participation of our fellow staff members. They have offered us tremendous amounts of support in terms of their excitement for the site’s progress, their eagerness to learn new skills and workflows, and their hard work in preparing more content for the site. We want to give a huge thank you to everyone who has helped in the development and promotion of the RAC Documentation Site!
What to Look Out For
We are continuing to transfer more and more content to the website, so please return regularly to see what new documentation we have available!
We are also training more of our staff members to convert existing Word documents and PDFs into Markdown files and to use GitHub to host and manage the converted documentation. By doing so, we strive to not only facilitate a significant migration of material to the site but to also empower our colleagues to feel comfortable with adding and editing content on the platform.