Write the Docs 2017 Day 1: Morning Presentations

Notes from the morning talks.
If there are things that you think could be improved, talk to an organizer. Learn, make friends, have fun!

Kate Voss – Error Messages: Being Humble, Human, and Helpful will make users Happy

Error messages are frustrating. Users will get the message and will think, now what? Attribute frustration to software, and breaks trust. Error message is an opportunity to rebuild trust. We don’t think enough about how error messages affect user experience.

Types of Error Messages

  • user error: very
  • system error: can be any kind of error. Not the user’s fault. It doesn’t matter to user. Need to explain what you know, and help them through it.

Good errors are:

  • humble: we’re sorry
  • human
  • helpful

Typical messages feel cold, shows no empathy: An unknown error occured (-50).

“Exception has been thrown by the target of an invocation.” makes no sense. Doesn’t communicate what’s wrong or what they can do about it. Should tell user what the problem is in plain language, the way you might talk to someone.

What you need to do about it, not just the error.

Humour? Even though example is funny, it doesn’t tell you anything, and is missing the other 3 Hs.

How to write errors:

  • important information first
  • fewer words
  • object first, action second
  • avoid passive verbs (makes it feel weak)

Users are already frustrated, and will scan through. Rebuild the trust that you might lose, so need to be careful.

Remember to:

  • acknowledge: that there is a problem
  • apologize: even if it’s not your fault
  • explain: what’s going on
  • help: to get where they’re going

How would you explain this to your grandparent?

Tom Johnson – Building navigation for your doc site: 5 best practices

Worked in a place where there was a usability lab; wanted to test documentation. Users struggle to locate the right content for help. How do you increase the user’s ability to find answers in docs? Wanted to make it so that users can find what they’re looking for. Wanted to use Design Principles to Tackle the Problem.

Design Principle: Hierarchy

Action 1: Group topics in product sidebars

Hierarchical organization is the simplest structure for visualizing and understanding complexity.

Hierarchies break down complexity: from a complex system to a list of parts; give idea of “whole”, but avoid deep hierarchies that don’t relay the whole.

Design Principle: Progressive disclosure

Action 2: navigate from doc set to doc set. Provide related resources section.

A strategy for managing information complexity in which only necessary or requested information is displayed at any given time.

Layer information at different levels: doc portal, product, section homepage, page. Start with pathfinder page, towards destination. Be selective what to show users at a given time so not overwhelmed.

Design Principle: Immersion

Action 3: allow navigation within the content.

A state of mental focus so intense that awareness of the ‘real’ world is lost, generally resulting a feeling of joy and satisfaction.

User is immersed inside the content, focused on the page. Even in help, users want to stay inline, more likely to click on links inline.

Bottom-Up Navigation:
* if you tell me I can do something, link to how.
* if you tell me I can use something, link to a description
* If you mention a concept of idea, link to description.
* Example: Wikipedia
* can be a lot decision points,

Design Principle: Desire Line

Action 4: Make popular topics easy to access.

Traces of use or wear that indicate preferred methods of interaction with an object or environment.

Make popular topics very visible.

Design Principle: Modularity

Action 5: Reduce information fragmentation. Consolidate tiny stubs of information or articles into self-contained articles.

A method of managing system complexity that involves dividing large systems into multiple, smaller self-contained systems.

Users read non-sequentially: you can just read everything in one place; table of contents give sense of whole at micro-level.

Building blocks =! presentation; can assemble chunks into more elaborate display.

Design Principle: Wayfinding

Action 6: Hang signposts along the way. You have seen the map, but as walk along, give signs to know where they are. Process map with contextual links, navigation sign posts. Provide context at the beginning and after, breadcrumbs, etc.

Amelia Abreu – Caring Systems: Documentation as care

Documentation is one of the areas of practice.

Care is the work of attending to expressed or anticipated needs.

Care has three forms: instrumental, emotional, and information care.

  • Instrumental help includes activities such as shopping, taxi,
  • Emotional support: listening, counselling, companionship, empathy
  • informational care: documentation is one type

Humans require more care than any other species. Caregiving is projected to be the largest occupation in the US by 2020. 81% jobs in service, 67% of economic output.

Care has a global supply chain.

We like to think that care isn’t as important as other work, and we like to make care cheap and invisible.

Who is doing the care work? Is our diversity problem actually a care problem?

Axioms for Care and Technology

  1. Care cannot be automated.
  2. Care is not a problem to be solved by technology, but rather a key human effort to be supplemented by it.
  3. Care is part of every human effort, thus it is racialized and gendered at global political economic scale.


  1. “Roll your own” solutions. What about users who are different?
  2. No dedicated resources for documentation = little to no documentation. Documentation is everyone’s/no one’s job. Too much reliance on relationships, and lack of scaffolding.
  3. Culture that discourages “stupid questions”. If ask for help, admit vulnerability.
  4. “Who is this for?” It depends on whom you ask.

Next Steps

How do we build systems where care work is as important as engineering work? Engineering work cannot happen without care work.

Everyone’s work is equally important.

How do we do better?

  • user research and docs
  • ethnographic user interviews to generate user flows and requirements
  • usability test the docs
  • RITE (Rapid Iterative Testing) the docs
  • participatory design and docs
  • org efforts for understanding and valuing care work rather than seeing it as a problem to solve or make invisible

Christy Lutz – You have already succeeded: Design critique guidelines make feedback easier

Sharing your work and getting feedback is part of our work. It can be painful and overwhelming, but you will survive.

Feedback makes you stronger.

What is good about feedback? Feedback doesn’t happen without you, leads to better working relationships (talk about what you don’t know), works.

What do you need? Identify stakeholders (including you), create a scope statement (I am sharing [early/mid/late] work around [problem] because [why] and I am looking for feedback around [specific focus for feedback] at this time, I don’t need [areas outside the scope of review]), write down feedback guidelines (broader and for every project; ask for what you need).

How to ask, give, and deal with feedback. Just start. Gather feedback by listening and repeat: your reviewers are thinking about how they can help, don’t need to sell your work.

How do you get people involved? Throw a feedback party. Others feel invested in your success. Feedback is easier when playing a role: black (critical, practical), yellow (optimistic), green (creative), red (emotional). Play with stickers.

Schedule a design review to follow up.

Gather feedback anywhere and everywhere; talk to your team. You know what it’s like to be a user. Give the kind of feedback you would want to receive. All feedback should start and end with positive feedback. Ask questions. Just remember, your role is the defender of the goal(s) of the project.

How do you deal with feedback? It’s not about you, it’s about helping people. If get a lot of feedback, celebrate because it means it’s an important part of an important project, and take a break.

How do you measure your results? Follow up. Does this support the goals of the project? Feedback is a discussion.

Reporting results: Appreciate reviewers. Not about winning. Goal is not about making everyone happy. The goal is your goal. Have your reasons and be ready to discuss, but don’t have to comment on every piece of feedback.

Teach design critique guidelines to your team. Feedback gets betters for your whole team and for you. It gets less painful the more people put it in practice.


cotton ball bats

Author: Cynthia

Technologist, Librarian, Metadata and Technical Services expert, Educator, Mentor, Web Developer, UXer, Accessibility Advocate, Documentarian

Leave a Comment

Please log in using one of these methods to post your comment:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: