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


Skip to comment form

  1. George H. Williams

    I’m definitely interested in participating in a session on this topic. It might also be worth our time to share suggestions for software that makes it easier to create screencasts and screenshot-based instructions.

  2. Amanda French

    I do really like Camtasia — and as it happens, TechSmith, its maker, kindly donated five copies of it (and other screen cap software like Jing and SnagIt) to THATCamp to serve as door prizes. Hadn’t yet come up with a way to give them away, except one set will be the prize for the bakeoff, so maybe we can distribute them in this session.

  3. Sheila Brennan

    I agree, I use and like Camtasia. It also has a screen capture program that is pretty good for us PC users who can’t use Snap-z.

    George, the new wiki might be a good place to share these kinds of things–good idea!

  4. George H. Williams

    @Amanda: Well, now I’m going to have to think about baking something!

    @Shelia: My thoughts, exactly.

  5. Jean Bauer

    Count me in! We definitely need better documentation. How else are we going to teach people about the value of our work?

Comments have been disabled.

Skip to toolbar