DPC

Obfuscate and Accumulate

Here’s an idea that comes out of a clear blue sky: we don’t talk enough about technical debt in digital preservation. It’s an important concept and one we could be working with.

Technical debt is a term used in software development to describe the costs that arise when an easy or cheap solution is adopted over a fully worked out, properly documented, long-term solution. Expedient or cheap solutions which don’t have forwards compatibility make future changes costly if not impossible. This cost accumulates "interest" as changes and upgrades are delayed and therefore become harder to achieve over time. The debt is a contingent liability: work can be deferred but cannot be avoided to maintain legacy systems, or to exit them in an orderly fashion. In worsening conditions, investment is diverted towards short term maintenance, which further increase the complexity of a legacy system, making migration harder and stifling genuine innovation. Left unchecked this ultimately reaches a bottom where either the system fails, or the business fails. Sometimes both.

My sense is that many agencies are accumulating technical debt which they don’t fully understand. Indeed, every agency that depends on technology for the delivery of products or services has a theoretical exposure to technical debt, and this has real world consequences.

A bold assertion follows – that, perhaps without fully realising it, the digital preservation community has been quietly and successfully building the tools and services that tackle and prevent the accumulation of technical debt. And so digital preservation is not a niche fixation for specialists, but a pervasive concern through the entire economy.

William Kilbride is the Executive Director of the Digital Preservation Coalition, and was General Chair of iPres 2022.

My tiny desk is full to overflowing. My keyboard is jammed between assorted packages and boxes waiting for iPres which opens next week in Illinois. DPC is helping to sponsor iPres this year again (more in a moment) so the generous offer of a table in the exhibition hall has precipitated a search for merchandise – tablecloths, stickers, pens, leaflets, brochures - all bound for Urbana Champaign. I’ve tracked down the last two remaining DPC scarves, and the very last DPC tie.  I am sure they will all make a wonderfully, professional splash so please do drop by and admire the artistic effect if you are in town, because it’s a chaotic muddle and crush just now.

This section of the guide provides information to help you create documentation, from understanding how things are done at your own organization, to selecting the right tool and creating illustrations.

• Understanding your own organization

• Tips for writing documentation

• Tools and platforms

• Templates and style guides

• Illustrations and diagrams

• Testing documentation

Understanding your own organization

Organizations create and manage their documentation in a number of different ways using a range of tools and platforms. Organizations may have particular processes in place that relate to documentation - for example around testing, communication, and sign off. It is important to find an approach that works for your own context and for that reason, there is some exploratory ground work that you should do to ensure that you approach the task in the right way.

• What digital preservation documentation already exists? It is likely that there is already some documentation within your organization. Find out what is out there already: Where is it? Who owns it? Is it up to date? What format is it in? Where are the gaps? Talk to colleagues to help answer these questions - there may be existing documentation that you don’t know about. Make sure to explain what types of materials can be covered by the term “documentation”. Colleagues may have their own resources that they do not realize fall into this category (for example informal checklists or ‘cheat sheets’ that document processes). 

• What is the process for creating documentation within your organization or department? Who needs to be involved? Is sign off or approval of the documentation required or encouraged? Having a formal procedure to follow can help ensure consistency and quality.

• Which tools, platforms, and file formats are used for creating documentation within your organization? Speak to colleagues about what works and doesn’t work and also find out how it is done in other departments - there may be different practices across your organization that you can learn from. 

• Are there documentation style guides or templates in place within your organization? You may be able to make use of these or adapt them to suit your own purposes.

Tips for writing documentation

• Take a flexible approach - be prepared to adapt your documentation as you go along in order to find a style that works for you and your intended audience.

• Try to get the basic structure of your documentation right before you start to fill in too many details - you may find it helpful to do this collaboratively or get feedback from colleagues at an early stage.

• A helpful tip from Write The Docs is to try to ensure your documentation is ‘skimmable’ - documentation can be long (often by necessity), and users are unlikely to want to read it all in a linear fashion. Having clear headings, a consistent style and keywords appearing as early on in paragraphs and list items as possible, will help a user quickly locate the section they are interested in.

• Your documentation should be easy to understand and interpret - try to write in ‘plain language’ where possible. See for example this guidance from New South Wales government. Also consider the accessibility of your documentation. There is a helpful guidance on writing accessible and inclusive content from the Australian Government.

• Consider the level of detail of your documentation - if documenting a process, typically it should describe what to do and how to do it. In some cases though, it might also be helpful to briefly describe why a process is being run or why a particular decision has been made. Justification for procedures can be useful in getting staff on board as they can see the rationale and benefit of the effort required. 

Tools and platforms for creating and providing access to documentation

There are many different tools and platforms that could be used to create and provide access to documentation and these all come with their own pros and cons. Establish what you have access to within your organization and consider what will best meet the needs of your audience. 

Some additional points to consider when deciding on a tool or methodology for creating and updating documentation:

• Who needs to be able to update documentation? One person or multiple people? If multiple people, how will this be managed?

• Is there a culture of printing documentation out in your organization? If so, can you use a platform that builds value into using the live (and therefore most up-to-date) version?

• How will you provide access to the documentation? Can you use a platform that displays all the available documentation in a logical and intuitive way, allowing a user to easily see all current versions of documentation and allowing for interlinking or cross-referencing between them?

• Do you need to make different elements of your documentation available for different audiences? Do you have a tool or platform that allows you to implement these access permissions?

• How frequently will your documentation need to be updated? If frequently, don’t put barriers in the way with the tools and platforms that are used (for example a process that requires documentation to be converted to pdf and uploaded somewhere after each update).

• Do previous versions of documentation need to be saved/retained? Either to be preserved as a record of what happened at a particular point in time, or to be able to roll back to a previous version where appropriate? If you have these needs, consider how the tools can support this. The section on updating and versioning documentation discusses this in a little more detail.

• How will you get your documentation out of the platform that it is created and/or hosted on? Plan for your documentation to outlive the platform or format it exists in. Your documentation may need to be preserved for the long term (see ‘Preserving Documentation’ section), and exit strategy should always be considered.

• Who owns the documentation? If you use a tool or platform (such as Google Drive) that assigns ownership of a document to a particular account holder, ensure a process is in place to retain access to this documentation should that individual leave the organization.  

As well as the tool or platform for creating and hosting documentation, you may also wish to employ a project management tool for helping to manage the process of maintaining the documentation. For example for tracking progress, keeping a record of issues or update requests and logging review dates. Focus group participants reported using a range of project management tools to aid the documentation process (for example Jira, Trello and asana).

Find out which tools some of our focus group participants use in our series of interviews. The table below provides an overview of some of the tools and platforms.

For further information about tools for documentation (and in particular, a really clear description of how to use tools such as GitHub and GitLab), take a look at this presentation from Nathan Tallman and Carly Dearborn. The whole presentation is worth watching, but if you are specifically interested in tools, watch from 16:12.

Templates and style guides

As discussed earlier in this guide, one of the characteristics of good documentation is consistency. Consistency of formatting, structure and language are all helpful in increasing usability, particularly with long documents or a large suite of documentation. Consistent use of a particular platform and/or file format is also helpful. A user will quickly become familiar with the style, format and conventions used and this will help them to retrieve the relevant information more efficiently. Some organizations use templates or style guides to help them to achieve this. A template can be useful, particularly in making sure that key navigational and structural elements (e.g. table of contents, page numbering) or information about document history (e.g. owner, creator, date of last update, date of review) are not forgotten.

Your organization may already have a template for documentation, either for your immediate department, a related department (e.g. IT), or a wider context. If your organization favors a particular project management approach or methodology, this may include templates and processes for documenting standard operating procedures. 

You may be interested in looking at the templates developed by the OSSArcFlow project. The Guide to Documenting Born-Digital Archival Workflows provides a template, including a legend for symbols and conventions used in the workflow diagrams that were created by project partners. 

Another useful tool is a style guide. This can be helpful in ensuring consistency in formatting and use of language. 

• Write the Docs has an extensive set of pages relevant to documentation style guides if you are interested in further reading on this topic. 

• The gov.uk style guide includes common sense advice on writing in clear and simple language (even when writing on quite specialist topics).

• The Australian Government also has a helpful style manual which includes (among other things) recommendations for grammar and punctuation and use of plain language.

Illustrations and diagrams

Documentation can be greatly enhanced with the addition of a screenshot or a clear and informative diagram. The presence of both images and text can be helpful where a variety of learning styles, preferences, and abilities are present within your target audience. Note, however, that a heavy reliance on graphical representations of workflows may not be appropriate for those with a visual impairment so do consider whether this information can be conveyed in an alternative way.

Screenshots are easy to create and incorporate into your documentation. They can really help with clarity - for example when describing how a tool should be configured it can be helpful to illustrate this with a screenshot of the relevant dialogue box. Note though that screenshots can become out of date quickly as the tools evolve, and excessive use can make documentation large and unwieldy. 

Diagrams can be particularly effective in helping to explain complex information, decisions or workflows. There are a number of tools available for creating effective diagrams and it can be helpful to look at examples from other organizations too.

Tools

The OSSArcFlow project provides some helpful advice on creating diagrams. The project team used LucidChart to create their workflow diagrams and also provided guidance on conventions to use to illustrate different elements within the workflow. See the OSSArcFlow Guide to Documenting Born-Digital Archival Workflows (page 38 to 41).

Several participants at the focus group meetings reported using Visio to document workflows - this is a useful tool that includes different conventions for different elements of the process. It was also noted that PowerPoint or Google Slides can be used to create simple and effective diagrams and this is sometimes a quick and easy way to get started.

There is further advice on creating diagrams within the Community Owned Workflows resource.

Whichever tool you choose to use to create diagrams, there are some problems and pitfalls to watch out for. Avoid overcrowded diagrams with illegible text. A balance needs to be struck between the amount of information included and the clarity and legibility of the end product. 

Examples

Here are some good sources of examples that you can look at for inspiration:

• OSSArcFlow project - a series of ‘as is’ workflows were created as part of this project and can be viewed here. These workflows were all created using similar tools and conventions.

• Community Owned Workflows (COW) - there are a range of workflow diagrams shared on the COW wiki pages - see for example the diagrams created for the Cloud-based preservation and access workflow for MXF and MPG video from the Wellcome Collection.

Testing documentation

Testing documentation is a great way of getting feedback from your target audience. Let your audience see the documentation that has been created. Ask them if it is clear and understandable. See if they can follow it or if they find any gaps. 

• One focus group member described how they tested their documentation with a colleague in the IT department. Though digital preservation wasn’t a part of their role, IT would need to step in and help if there was a system problem and digital preservation staff were unavailable. Having an IT colleague work through the documentation was really helpful in ensuring that it was clear and gave confidence to both parties that problems could be resolved in an emergency. 

• Another participant tested documentation in an informal way with other members of the Archives team. Doing this helped build up the confidence and awareness of other staff members about digital preservation activities. 

This section of the guide answers some of the key questions around documentation:

• What should be documented?

• Why should we document?

• Who is it for?

What should be documented?

There is no definitive list of the types of documentation that an organization needs in order to carry out its digital preservation activities, though if you are considering certification there may be a list of documentation that is required as evidence (see for example the CoreTrustSeal Trustworthy Digital Repositories Requirements 2023-2025 which includes details of suggested supporting evidence that could be submitted). 

The list below is not exhaustive, but provides a range of examples mentioned by participants of our focus groups. Some of these have been grouped under different parts of the digital preservation workflow.

• Acquisition transfer and ingest - for example, acquisition, transfer or deposit procedures, pre-ingest and ingest procedures, procedures to handle specific sorts of media carriers, normalization procedures, guidance on appraisal and selection of content.

• Bitstream preservation - for example, integrity checking procedures, procedures for copying or moving files, details of storage locations used.

• Content preservation - for example, technology/preservation watch review process, and detailed instructions on tools and processes for preservation actions.

• Metadata management - for example, guidance on metadata creation, documentation of metadata standards and controlled vocabularies in use.

• Discovery and access - for example, procedures for managing and providing access to digital content.

Documentation may additionally include staff roles and responsibilities around digital preservation, technical details on system integrations, systems architecture, asset registers for servers and storage, access procedures for digital preservation/computer forensics facilities, lists of hardware and software available in-house, exit strategy and service level agreements with third parties.

Why should we document? 

Some of the benefits (and risks) related to documentation are summarized below. Note also that in our interviews with selected focus group participants you can find about why documentation is important for them and their organizations (read their answers here). 

Consistency

Good documentation is important for ensuring that digital preservation processes are carried out consistently no matter who is doing it and at what point in time. It ensures that the workflows are repeatable and reproducible and that processes are standardized within an organization.

Training and knowledge management

Good documentation is important for supporting staff to carry out digital preservation procedures. Whether you have new staff who need to access documentation as part of their training, or whether you want to increase levels of confidence in digital preservation procedures for existing staff members, documentation is key to sharing this knowledge. 

To communicate with others

Good documentation is an important tool for a range of advocacy and knowledge sharing activities, both internal and external. There may be situations (beyond training staff) where it is helpful to share information about processes with others, for example: 

• to demonstrate to donors and depositors that good practice is being followed.

• to show users of the digital content how authenticity is maintained over time.

• to share knowledge and compare processes with other organizations (the OSSArcFlow project is a good example of this).

• to discuss digital preservation activities with internal stakeholders from different departments and help them understand their responsibilities in the overall process. 

Having thorough documentation of operations makes it easier to share and communicate workflows and processes.

To support continuous improvement

Good quality documentation enables the evaluation and analysis of processes and procedures, both by those working within the organization, and by third parties if appropriate. Documentation allows for the identification of gaps or operational bottlenecks and could lead to further improvements. Documentation opens up opportunities for processes to be more easily analyzed. Note that the OSSArcFlow project provides an excellent example of how this has worked in practice. It was noted that the process of creating the documentation itself was important in helping the project partners to recognize and articulate their pain points, and to then take steps toward addressing those issues.

To support certification or accreditation

Good documentation is an essential requirement for an organization applying for certification or accreditation. Depending on the scheme or standard that is being applied for, documentation will be required as evidence to demonstrate that digital preservation is being carried out to an appropriate standard.

For transparency and authenticity

Being able to prove the authenticity of preserved content is essential in digital preservation. Being open and transparent about what has happened to that preserved content is important. Good documentation supports this by ensuring the chain of custody and provenance is captured and a historic understanding of processes and working practices is available in the future. It will allow future custodians and users to understand the workflows, actions and decisions that were taken at different points in time, thus enabling them to assess the trustworthiness of the preserved information.

To support internal planning and management

Good documentation supports the effective management of digital preservation activities in many ways. It can be used to support requests for resourcing, to manage evolving needs and aid forward planning, to assign clear roles and responsibilities to staff, to better understand risks and mitigate them and to better understand the impact of organizational changes.

Finding the right balance…

Remember that it is important to find the right balance around documentation. Whilst noting the benefits of documentation, there are also potential risks around creating too much documentation or having inaccurate or out-of-date documentation. Documentation takes time and effort to create and maintain and that of course means less time spent on other activities. It is important to understand the commitment and ensure there is time set aside to keep documentation up to date and relevant. 

Ensure also that the presence of documentation doesn’t lead to a stagnation of processes and procedures. Though stability is a good thing, in a discipline like digital preservation it is important there is also space for new ideas and innovation. Don’t stick to doing the same out-dated process simply because that is what the documentation says you should do. There should be a process for reviewing and evolving practices where appropriate and of course to ensure that documentation is also updated accordingly.

Who is it for?

When creating any form of documentation it is important to consider who you are creating it for and why they might need to access it. There will be some variation depending on your organizational context. The table below defines some of the key audiences to consider. 

Points to note:

• Do not assume that you need to write your documentation to meet the needs of all of these audiences, but do carefully consider which you are serving, as this will impact decisions about the level of detail, format, language and platform you use when creating and providing access to the documentation.

• Remember to consider future audiences as well as those who will need to access the documentation now.

• Note that the level of digital preservation knowledge of your readers is likely to vary depending on the specific audiences you have in mind for the documentation. Ensure you adjust the content as appropriate. 

As a community, we know much about preserving records, but we may not automatically apply this knowledge to our own documentation. Consider which digital preservation documentation should be preserved for the long term. You may already have a retention schedule within your organization that covers procedural documents, but digital preservation documentation may need to be retained and managed for longer. If your digital preservation documentation describes processes and activities carried out on digital content, you may need to retain this as a permanent record of how content was processed and handled at a certain point in time.

Digital preservation practices within any organization will evolve and develop over time as tools, policy, and requirements change. Processes and procedures for born-digital archives are likely to change and develop at a much faster pace than their analogue counterparts. Digital preservation documentation should therefore be reviewed and updated regularly in order to keep it current. The more detailed the documentation, the more quickly it will go out of date. 

Revising and updating documentation should be a reasonably straightforward exercise. The biggest challenge may be carving out the time to work on it - maintenance tasks like working on documentation are easy to neglect in favour of more exciting or urgent priorities. You may be interested in the work of The Maintainers, and specifically a sub group called The Information Maintainers which supports the maintenance of information and those who manage, maintain, and preserve information systems. Read more about this community here. Our focus group attendees describe how they manage updates and versions in the interview section of this guide but you will also find some tips and advice below.

When updating documentation there are a few things to take into consideration - namely, review frequency, versioning and communicating any changes.

Frequency of update

Documentation should be actively maintained and should not be allowed to get out of date, but realistically, how do you achieve this? Updates may be on a schedule that you set, or may be reactive based on triggers that may occur. 

• Scheduled updates: Just as is good practice with policy and strategy documents, it may be appropriate to include a review schedule on procedural documentation. Whereas a digital preservation policy may only need to be updated every 3 years, procedural documentation is likely to need more frequent updates. You may find it helpful to schedule in a regular time to review and update documentation (at least annually). Set yourself a reminder using your calendar or task management system or tie this in with an existing activity in your calendar such as an annual reporting or review meeting. 

  • In a DPC workflow webinar, Julia Miller gave an example of how an annual steering meeting can act as a trigger for her to work on documentation and also noted that she sometimes blocks out Fridays for documentation tasks too. It is good to have a regular point in your calendar when you carry out maintenance tasks such as this. 

• Reactive update: Updates may also occur due to specific triggers - for example, if your digital preservation system is upgraded or a new tool is added to your workflow, your documentation will need to be checked and refreshed. Another situation that may lead to a documentation update might be the recruitment of a new member of staff working on digital preservation activities. As they familiarize themselves with digital preservation processes and procedures and work through documentation, this can be a trigger for updates if any aspects of the documentation are found to be ambiguous or unclear.

Managing versions

It is important to have a consistent method of versioning your documentation. It is good practice to clearly mark your documentation with a version number as well as a date. Some platforms and tools used to create digital preservation documentation (for example Git repositories and wikis) automatically manage and maintain previous versions as edits are made. If the system you are using does not do this, ensure you have a consistent method of recording document versions as edits are made. Standard practice is to use a system of numbering that increases in small or large increments depending on whether a major or minor update has occurred. For example:

• Version 1.0 - first published/released version

• Version 1.1 - minor edits have been made

• Version 1.2 - further minor edits have been made

• Version 2.0 - a major revision has been carried out

If not utilizing a system that manages versioning, it is good practice not to rely solely on file naming conventions to record version number. As mentioned under templates and style guides it can be helpful to include a table containing key information relating to the document (including versioning information).

You may find it useful to define a policy, both for version numbering and for the maintenance of previous versions (for example whether you overwrite the previous version or maintain it for your records). An example from the University of Glasgow was provided by one of our focus group and may be a helpful point of reference. See also the section of this guide on the preservation of documentation.

Note that if you are using a platform that tracks and maintains all versions, it may be wise to capture a periodic snapshot. When migrating from this platform at some point in the future it may not be possible (or even desired) to capture all previous changes and versions.

Communicating updates

Once your documentation is updated ensure any relevant information about the update is communicated appropriately. If major changes have been made, the update may need to be accompanied by additional testing, communication and even training. Even if minor tweaks have been made, it is important to ensure that your audience knows there is a new version, particularly if you have a working culture where individuals print out copies or download local versions of the documentation to use rather than accessing the live version.

Focus group attendees spend some time brainstorming some of the features of good and bad documentation using a Jamboard. The key points made are summarised in the table below. This table may be helpful in helping you assess existing documentation or set out some basic principles for the creation of new documentation.

Why is digital preservation documentation important to you and your organization?

Digital preservation documentation is important to the Art Gallery of New South Wales (AGNSW) and myself for a number of reasons. Firstly, digital preservation is a complex and ever evolving field of practice within collection management and access and, because of this, documentation allows for assessment of and justification for digital preservation tasks, such as bagging, disk imaging, checksum generation, within the ongoing collection management tasks of the Art Gallery of NSW. It also allows for all staff, beyond initial training, to understand how digital preservation may fit into their daily tasks, their importance, and how they can undertake them individually with minimal oversight and troubleshooting. 

Moreover, documentation allows for staff to test out and evaluate new workflows and do a risk and significance assessment of the collection and which digital preservation tasks may be most suitable for different collection sets, both generally and at particular points in time (such as very busy exhibition openings where only the core digital preservation activities may only be undertaken with the other being noted but only actioned at a later time). 

What tools or platforms do you use to create and provide access to your documentation? What works or doesn’t work well with these tools or platforms?

For the most part, AGNSW uses Sharepoint as the central hub for creating and providing access to documentation. This allows me to create draft workflows and share amongst digital preservation and time based art conservation to contribute and test workflows and instructional guides before sharing more widely or publishing on the Staff Hub intranet page. 

The potential drawback to creating documents on Sharepoint as the main hub is that other staff members may accidentally edit or delete. This can be overcome by editing sharing permissions to the main documents so they can only view certain documents or ensuring the only changes that are made via mark up or comments. This is also done so to avoid (or at least reduce) the possibility of multiple versions of the same file floating around in the system that would be more likely to happen if shared via email as an attachment. 

When do you create documentation and how often is it reviewed and updated?

Documentation is created whenever there is a process that is either developed or changed, or either impacts or is impacted by other existing collection workflows, such as curatorial acquisition workflows. 

What is the update process and how do you manage versions?

The update process is fairly manual at the moment, with each file version having the date recorded in the filename. This means that any changes to the file are saved as a new version with a new date. The older files are archived and retained on Sharepoint for reference for a period of time before deleting. This avoids the need to retain, and resulting confusion, in having multiple old and outdated workflow documents all kept in the same location. 

Do you have an example you can share with us? (even just as a screenshot if not publicly available)

What is next for digital preservation documentation at your organization?

Next steps include reviewing existing workflows as part of testing and implementation processes, as well as review of instructional guides as part of Working Groups. Once finalised, they are to be published on Sharepoint to accompany wider departmental training.

Are there any resources or examples that have been really useful to you in creating your own documentation?

I actually found that, beyond copying the existing documentation, that business briefs to managers and executive justifying new workflows and project funding, and requirements gathering from business areas about filling needs based gaps help identify how documentation should be written to maximise buy-in and training outcomes for staff.  

What tips do you have for people starting out on documenting their digital preservation activities?

Start any documentation by just trying to clarify it for yourself based on what you actually do each day, as more often than not, actually thinking about and explaining what you do is more difficult than people realise (especially when you do it do often day to day that it becomes second nature and you may lose sight of the larger reason why you’re doing it). Using that as a template, edit it according to the needs of those outside of your immediate business unit (digital preservation). Following initial trial run throughs with people, this is a good way of seeing whether your documentation is easy to understand and follow without you needing to explain each step of the digital preservation activity with them. If it is too detailed, go back and simplify explanations as there is little point in documentation if the detail is correct but it is too complex and confusing to follow and be successfully implemented and adopted longer term. 

Why is digital preservation documentation important to you and your organisation?

Since releasing the first version of our digital archiving workflow in 2021, we have engaged in an ongoing effort to formalise our digital preservation service: from identifying the stages in our digital archiving practice and articulating the processes, through which each stage is initiated and completed; to creating guidelines for completing these processes and providing a common terminology across all University areas involved in digital preservation. 

Documentation is instrumental in this effort, both as an expression of work systematisation and as a shared source for guidance and review of digital preservation practice. It helps us communicate our work horizontally and vertically within the University and across many stakeholders – an otherwise challenging endeavour in a large institution like the University of Glasgow.

What tools or platforms do you use to create and provide access to your documentation? What works or doesn’t work well with these tools or platforms?

We are currently using SharePoint pages to create and provide access to our documentation within the University. For public documentation, we use open platforms as much as possible – our digital archiving and archival forensics workflows are available on Community Owned Workflows (COW), which is part of COPTR.

SharePoint is a convenient platform for sharing resources with colleagues, managing access permissions for viewing and editing, and for maintaining version history. As a platform managed by the University’s IT Services, there is reassurance around availability, maintenance, support and uptime. What’s more difficult in SharePoint is exporting the documentation in formats that are suitable for migration in another environment and for preservation – we do need to preserve our own digital preservation documentation! 

There are workarounds, such as printing the SharePoint pages as PDF via the browser or copying the content in plain HTML, but these inevitably come with caveats. Open platforms like the wiki-based COW and COPTR facilitate exports and preservation of contents, but their sustainability and maintenance relies on the community and not-for-profit organisations.

When do you create documentation and how often is it reviewed and updated?

We create and review/update documentation in three ways: planned, proactive and reactive.

Planned documentation creation is commonly included in larger digital archiving and preservation projects, where the outcomes need to be documented and shared with colleagues both within Archives & Special Collections and across the University. For instance, we recently created guidelines for the quarantine and conservation of computer storage media that we acquire as part of collections. The guidelines form part of a wider project to review and streamline conservation and quarantine procedures for new acquisitions.

We proactively create documentation when we anticipate that it will be required for forthcoming digital preservation activity. And sometimes, we need to reactively create documentation for activities already undertaken or for activities whose completion relies on undocumented staff expertise or “tribal knowledge”.

Equally, we have planned review cycles – all documentation below version 1.0 is reviewed every six months (if not sooner), and yearly after that. Proactive and reactive reviews follow a reasoning similar to documentation creation. Our aim is to update documentation with changes post-review as soon as possible, within a month as a ballpark, before it gets buried under other priorities!

What is the update process and how do you manage versions?

The update process depends on the nature of the documentation and the stakeholders involved in its creation and application. For instance, we are currently working on guidelines for ingest of digital materials into our digital preservation environment – these are created and updated by the digital preservation team in Archives & Special Collections. Conversely, the digital preservation risk assessment and risk register are updated as a collaboration among units across the University – specifically as an action of our Digital Preservation Working Group.

For resources on SharePoint, we use the built-in version history and document version control tools. For all digital preservation documentation, we use the good practice and information guidance on version control produced by the University’s Records and Information Management Service (RIMS).

Do you have an example you can share with us? (even just as a screenshot if not publicly available)

Our digital archiving workflow documentation includes eight sections:

• Minimum requirements, an outline of the base-level processes and actions required to complete a workflow stage.

• Mandatory processes, a detailed definition of these processes and actions – we aim to keep process definition succinct and, where possible, defined as a set of step-by-step instructions.

• Optional processes, a definition of any additional processes that are complementary to mandatory processes.

• Dependencies, any relationships between the processes of one workflow stage and others. These generally align with the dependencies/connections/relationships specified in the digital archiving and archival forensics workflows.

• Tools and forms, any software, tools, apps and forms that are necessary to complete mandatory and optional processes.

• Definitions, an optional section where definitions to specific terminology are necessary to increase clarity and understandability of the documentation across different stakeholders.

• External resources, a list of links to any external documents, guides, policies etc. used as reference material.

• Document history, a table where we record the current version number, staff member(s) who created, updated and approved the documentation, and dates of creation and last update.

Here’s an example, showing the guide for the Acquisition stage of the digital archiving workflow:

What is next for digital preservation documentation at your organisation?

We are currently working on a series of guides to document processes and activities required to complete each stage of our digital archiving and archival forensics workflows. It’s a substantial piece of work that will hopefully be completed by the end of 2023.

Are there any resources or examples that have been really useful to you in creating your own documentation?

The Digital preservation at TIB guides, maintained by the German National Library of Science and Technology, were an excellent starting point – both in terms of content and structure. We also used digital preservation resources created by The National Archives and OCLC research as inspiration for structuring and presenting our own digital preservation documentation.

What tips do you have for people starting out on documenting their digital preservation activities?

• Preparation is key – collect all relevant resources and liaise with stakeholders as necessary to gather content. It’s generally easier to create good documentation in the first place, rather than constantly amend.

• Best is the enemy of good – it’s great to aim for the highest possible quality of documentation, but not if this deters or prevents from creating the documentation in the first place!

• Keep it succinct and meaningful – long, convoluted, unclear documentation kind of defeats the purpose. There are much better chances that documentation will be followed and implemented, if it provides all the essential information in clear language, with step-by-step instructions wherever possible. Nothing wrong with bullet points!

• Structure and presentation are important – a well-presented, well-structured documentation helps with clarity and allows readers to focus on or navigate to specific sections of interest.

• Cross-reference – it becomes cumbersome to follow documentation when references to other parts, guides, external sources etc. are not linked.

• Who’s the audience? – we can’t expect everyone to be the ultimate digital preservation guru – even digital preservation experts! Documentation needs to be thorough enough for people of different levels and expertise to understand. It can also play a significant educational role – new staff, students, trainees, newcomers to digital preservation can all benefit and learn from good documentation.