-
Notifications
You must be signed in to change notification settings - Fork 9
Research 5 Testing technical documentation
To fully support our colleagues who will be contributing to the guides and methods over time, we wanted to test how usable our technical documentation was. To that end, we did semi-formal, semi-casual testing of what we'd written as we went.
Our loose protocol went like this:
These are beats to hit, but not necessarily the exact words to say. Let the conversation flow naturally. These questions will be tailored and iterated upon after each session in order to work towards getting progressively more targeted feedback. Abbreviate the introduction for participants who know us or those we work closely with.
Insert any context about the participant or project here: they might have already given some context for how they've interacted with this document or docs like it.
- Ask about their day, be a general human
- I’m ___ (name/pronouns/job title) and we also have ____ (name/pronouns/job title)
- We’re here today to try to improve our technical documentation, with your help
- Thanks for joining us
- We’re going to ask you to look at our documentation and tell us what works, what doesn’t, what you might change to make it easier for you to use
- We can stop at any time, or just let us know if you need to step away for any reason
- If we’re silent, nothing’s wrong: we’re just taking notes or giving you an opportunity to tell us more
- You can’t do anything wrong today. We’re not evaluating you, you won’t hurt our feelings, and you can be honest with us. We’re here to learn about how this works for you and your expectations.
- Any questions before we begin?
- Barriers
- Pain points
- What was helpful and not
- How (or if) they would use these docs
Think about the last time you started working in a new repo: how did you approach understanding it?
Let’s focus on the table of contents. Please talk out loud – what are your initial thoughts?
Listen for:
- Who is the intended audience for this document?
- What’s this for?
- What are some topics you expect to see here? Any topics missing?
- How did you find the organization of content? The order of content?
- Are there any titles that you’re not sure about?
Take a moment to scroll through the document. Can you say out loud what you’re thinking?
Listen for:
- Do the heading titles accurately describe their content?
- Too detailed/not enough?
- Formatting?
- Is there anything you’d like to know about this repository that you didn’t find in this document?
What is one thing we didn’t ask that would be important for us to know? Is there anything else you want to say, or you wish we’d asked? If you could change one thing tomorrow with a magic wand, what would it be? This could be something in the process, the product, or anything really.
Thanks for taking the time to meet with us today. We appreciate your candor and sharing your experiences with us.
- Do you mind if we keep your contact information on hand and follow up with any questions we might have in the future?
- Might we contact you for another testing round?
- Do you have any questions for us?
- Get in touch if you have any further thoughts or questions
Revise the docs!
- What stood out about this interview?
- What are these participant's goals? What matters to them?
- What are their challenges? What are their unmet needs and wishes?
- What stories did they tell?
- What about this session reminded you of past sessions (if applicable)?
- What went well about this session?
- What went poorly (for example, uncomfortable topics, awkward transitions, etc.)?
- How could the interview guide be updated before the next session?