This past Saturday, I headed to the campus of the University of Washington for InfoCamp Seattle 2015! Long-time readers of the blog, know this was my third time there. It’s a wonderful “unconference” where the schedule is assembled at the conference, and many of the sessions are open ended and discussion oriented. The attendees—designers, programmers, information architects, librarians, and others—is wonderfully curious, and so I always go excited to watch and listen.
I spent my day in two accessibility sessions, a digital literacy session, a very-well-attended conversation about the controversial Seattle Public Library rebrand, and then, on a bit of a whim, a brainstorm about documentation led by me!
Brainstorm: How Do I Get People to Use Documentation?
Turnout was great and I came into the session hoping to help brainstorm answers to the question “how do I get people to use documentation?” Even as a small one-person company, I write documentation of any custom features I build for my clients. Once written, it’s the fastest and most-straight-forward way for clients to access support, but that doesn’t always mean it gets used.
I tweeted out pictures of the notes I took, and below I’ll write those out with a little more info as necessary.
Documentation whiteboard pics from my session at #InfoCampSEA / @infocampSEA ! pic.twitter.com/zW7zPqVCmr
— Mark Root-Wiley (@MRWweb) October 17, 2015
Attributes of Bad Document
Bad documentation is:
- written by experts and assumes too much prior knowledge.
- unstructured, unmaintained, and unwieldy.
- not always relevant to the issues people need help with.
- often used once and forgotten by both users and documentors. It may grow out of date or be updated but no one notices.
- unclear on the version of the product to which it applies.
- written to too many audiences, the wrong audience, or no audience at all.
- too broad or too specific.
- presented in the wrong format or only one format.
- displayed out of context and hard to actually use while following.
Attributes of Good Document
Good documentation is:
- a balanced mix of examples and description.
- supported by management and all users.
- presented in multiple formats including images/screenshots, animated GIFs, videos with transcripts, and “inline” help within the real interface.
- searchable.
- well organized and provided with appropriate navigation.
- clearly written, avoiding jargon and using synonyms and plain language.
- translated by humans, if translated.
- audited and updated regularly (for products that change), with set “content governance” schedules and policies.
- multi-directional and inclusive. Users can give feedback and ask further questions.
- in a useful place where it’s fast to access and use.
- concise.
- created and released at the same time as the product it documents and maintained accordingly.
- focused on the highest need areas, answering the most-asked questions.
Encouraging People to Use Documentation
Finally, I asked the group how to get people to use documentation.
- Use opportunities of organizational turnover—when documentation is required whether you want it or not—to improve and start practices.
- Refer to documentation when providing support (by email, during phone hold messages, etc.).
- Train people how to access and use documentation.
- Create opportunities for successes using documentation.
- Have other people contribute to the documentation or own a piece of it.
- Allow people to subscribe to updates of documentation.
- Force people to use documentation before requesting support.
Conclusions
We didn’t have any big conclusions, as this was mostly just a brainstorm. However, as you can tell from my bolding above, I was really excited by this:
[To encourage use of documentation,] create opportunities for successes using documentation.
That feels right and seems like something I can do. I already show people documentation during trainings, but the next time I do it, I’ll have them actually use it to learn a skill.
Chicken or Egg?
One person aptly noted that if you have bad documentation, nobody uses it, but if nobody uses your documentation, it’s hard to justify putting effort into it.
For those of us that believe in the power of documentation, I think it’s on us to follow the good, avoid the bad, and then direct people to documentation with a smile and help them use it.
One thought on “Documentation Brainstorm (Reporting Back from InfoCamp Seattle)”