Documentation: Love it or Hate it, We Need It

How does the availability, writing style, and level of completeness of documentation influence our willingness to use a digital tool or to engage in a project? More important, how does it effect the core audiences for our projects?

I use the term “documentation” to refer to any set of instructional writing or media (printed and/or online instructions, user guides, podcasts, screencasts, slideshows/screenshots, et al) produced to support the use of a digital tool, process, or project.

Documentation is challenging, because it is time consuming and requires the creators of a project to share processes and details that often have become naturalized. When working closely with a project, writing clear instructions for users with different intentions, levels of technical knowledge, and commitments to digging through pages to find answers is hard. Even though it is hard, and sometimes we don’t enjoy doing it, providing good documentation is akin to creating an accessible website.

Documentation, similar to code, is a specific type of writing that often is not recognized as scholarly or substantive work. How can we elevate this type of writing to something that can be quantified or “count” for project participants who work in different professional positions?

I would like to spend some time discussing what makes good documentation and exploring the following questions:

• How much time do you spend using any type of documentation?
• How much time have you spent writing or contributing to any documentation/codex?
• If you write it, will they read it?
• Have you ever asked for user feedback about a project’s codex or user guides?
• Have you ever stopped using a tool or a project because there was not sufficient documentation to assist you?
• How does the authorial voice adopted by documentation writers influence how someone uses it? Does this matter?
• Should documentation contain multiple voices, or at least provide the opportunity for many users participate in its creation?
• Are there common elements you find lacking in most codexes?

Perhaps throughout this session, we can collaborate on a document listing suggestions/recommendations for DH project documentation.

______

Thanks everyone for a great session: docs.google.com/document/d/1jjJL75EboctzXbH0wd5sD899xRdT5TDGhx_E9U2wyj4/edit?hl=en_US