As a founding member of the team and project co-lead, Liz Milewicz shares her thoughts on documentation for Project Vox and why documentation—as an object and a process—is a crucial part of the team workflow.
The life-changing magic of documentation
The life of a long-term digital publication can be messy. Team members come and go, and with them important information that helps the project function: critical steps in a workflow, the location of key files, even logins and passwords to shared team resources. In the day-to-day business of running a project, keeping good records and tidying up don’t always rise to the level of importance that they might—and arguably should, if a project is expected to continue beyond initial phases or team members.
Since we started Project Vox in spring 2014, over 50 students, faculty, and staff have served on the team, helping to develop, publish, or promote biographies, bibliographic guides, and teaching resources on early modern women philosophers. A large and fluctuating team (many of whom are volunteers) might seem at odds with an initiative to produce well-researched and well-written content, particularly when many of those team members do not hail from philosophy departments or do not already possess strong research skills or a background in digital publishing.
Enter documentation. When new members join the team, descriptions of project goals and team member roles help orient new team members to their responsibilities, as well as the tools and resources they will need for the job. From guides on conducting images research and determining re-use requirements to checklists and workflows for completing entry drafts and circulating them for external review, documentation is crucial for sustaining the project‘s progress and momentum. Documentation also eases and encourages participation within the team: templates and workflows provide direction and consistency; checklists reduce ambiguity about expectations; a well-organized file-management system makes collaboration less complicated.
Yet, to claim that documentation is useful is one thing. To create and maintain documentation that is actually useful is quite another. Seven years with Project Vox and counting, here are three lessons I’ve learned about creating useful documentation:
1. Use documentation (and document your own work).
While we may often think of or refer to documentation as a thing, it is as much a verb as it is a noun. Both in using existing documentation and in regularly recording and reflecting on our work, we create the conditions for making documentation useful.
First, and most obviously, documentation is only useful if it’s used. Documentation that’s hard for team members to find or understand isn’t likely to to be used. Sometimes documentation aspires to an idealized practice that ultimately doesn’t match the reality of our work and sets an unnecessarily high bar for process. For example, early in our project we set up a series of folders and tags for tracking when content moved from drafts to review to staging to publication. This highly structured system attempted to account for and manage a range of content types and processes and help us keep track of when work was completed. But it relied on all team members learning the system and manually moving their content as appropriate. Ultimately the system was too complex, requiring us to spend more time training team members and managing the system than was reasonable for a mostly student and volunteer team who wanted to do research and publishing. As we struggled with this process, we came to recognize that, though records and practices may look elegant and appropriate, the ultimate determination of whether they’re useful is whether they’re actually used.
Second, documentation continues to be used and useful when we thoughtfully adapt it to new ways of working. We check this both by using existing documentation and by recording and regularly reflecting on our own work. Regular use of documentation helps us test whether it still makes sense and is appropriate. To be clear, this is not just so we can find shortcuts and make work faster and easier; rather, we want to make sure that, in insisting on a process that’s difficult or unclear, our documentation doesn’t inadvertently encourage someone to ignore it or seek less inappropriate workarounds. Regularly recording and reflecting on our work helps us recognize patterns in our process and opportunities for efficiency. By reflecting on our process throughout, rather than at the end, we’re more likely to capture the reality of our work (e.g., time involved, critical steps, expertise required) and thus better communicate the resources necessary for planning that work in the future.
2. Develop and review documentation with others.
Especially for projects intending to operate for some time and with changing team members, documentation should not be constructed in isolation without input or feedback from others. Even if an individual was admirably diligent in documenting their own work, the processes that may have worked well for them (“Write in black pen, make edits in red pen”) may not necessarily work for others (“I’m color blind – where are the edits?”). Further, someone else’s process (e.g., using color and text formatting in Excel spreadsheets to help organize information) may not work for the project as a whole (e.g., color and text formatting aren’t meaningfully captured when creating preservable or shareable .csv files). Most importantly, we want to make sure that we’re thinking holistically about the impacts of process: what are the implications for future use of this image if we’re not documenting restrictions for use in social media? how will we be able to migrate, re-use, or share this bibliographic information if we’re not organizing it within a citation management tool?
We’ve found that routinely talking through our documentation and processes as a team can help us ensure that it makes sense for everyone and meets the needs and goals of the project as a whole. While such collaborative activities may be commonplace among some groups (such as code review and sharing as part of software development), humanities students and scholars may find that just talking about their research process with others is strange and uncomfortable, let alone developing a collaborative practice. For that reason, making discussion of documentation easy and normal is just as important as committing to a documentation practice itself.
3. Provide infrastructural and cultural support.
On that last point, we found that at least two factors can help promote actively useful documentation: a technical infrastructure that facilitates the collaborative dimension of documentation practices; and a team culture that encourages shared development and use of documentation. A key element of technical infrastructure is a collaborative file-management system. Our team uses Box to create, edit, and organize documents; share documents with others; create local links to external documentation; and help us track versions and reduce duplication. Over time, with better understanding of Box as well as our team processes, we have made it easier to find files and understand how to use them. This, in turn, helps improve our documentation: if the team cannot find and understand the documentation, they won’t use it; and documentation can only be as good as its use, since this use surfaces where improvements can be made.
But no tool can solve a social problem: If the team culture doesn’t promote regular use of documentation or individual and collective efforts to document work, even the most elegant and relevant documentation will sit unused and therefore useless. Certainly documentation benefits from tool training and preliminary introductions to team documents when new members join. But the greatest benefits accrue when team members are expected to document their efforts regularly as part of their work; demonstrate and share their use of documentation as part of presentations on their work; and regularly review and invite feedback on their documentation. An added bonus of normalizing documentation use is that it makes the inner workings of the project and the effort required to produce it more obvious to the whole team—which in turn can help educate everyone in how to do this work and also cultivate a deeper sense of appreciation for the work and contributions of others.
Needless to say, documentation is a work in progress. Our attention to record-keeping, file-naming, workflow logs, and organization is a habit developed over time, aided by the thoughtful efforts of many team members. We’re grateful that making our work more transparent and replicable helps others quickly assimilate and contribute to Project Vox. At its heart, documentation centers both our practices and our values, helping to maintain consistency in our work and to ensure that Project Vox continues to support and encourage new members of our team.
Liz Milewicz is the co-lead of Project Vox, head of the Digital Scholarship and Publishing Services department, and co-director of ScholarWorks: A Center for Scholarly Publishing at Duke University Libraries. She has been actively engaged in digital project development since the mid-2000s, during which she has frequently used, developed, or wished she had documentation.
