Creating Documentation

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.