Write the Docs 2017

This month's post includes my notes and thoughts from Write the Docs 2017 conference in Portland Oregon.

Overall, I had a very enjoyable and educational experience (just like last year). However, this year, I had the pleasure of volunteering to help set up the conference. I worked with a great team and look forward to volunteering again next year.

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

Presented by Kate Voss

Make the error messages more human

• Example of a very unhuman message: "Exception has been thrown by the target of an invocation."

Color warning message may be an issue to some users. Use icons in conjunction color.

Emoticons and/or graphics (humorous, cute, brand-related, etc.) puts a different face on the error message but keep in mind in needs to be appropriate for your brand and audience

Items to consider when writing error messages:

• Put the important info first
• Use fewer words
• "Object first, action second"
• Avoid passive verbs

Remember to:

• Acknowledge
• Apologize
• Explain
• Help

---

My take away: If you are tasked with making error messages "human", know your audience and write short but information messages accordingly.

Building Navigation for Your Doc Site: 5 Best Practices

Presented by Tom Johnson

• Apply design principles ("Universal Principles of Design") to tackle your navigation problem:
  • Hierarchies break down complexity
  • Hierarchies give an idea of the "whole" and show potential related topics
  • Avoid deep nesting
  • Navigate from doc set to doc set
  • progressive disclosure
  • Layer information at different levels. For example:
  • doc portal home
  • product home
  • section hom
  • page
  • Allow navigation within content
  • Even in help, users want to stay inline (sidebar navigation vs. inline link); users are more inclined to click links inline to the document rather than the sidebar navigation
  • Use bottom-up navigation
  • If the viewer reads something that he can do, use, or consider (concept), link it to the respective document
  • Too many links may cause issues with the viewer's decision points (for example Wikipedia entries)
  • Make popular topics easy to access
  • Desire line: "traces of use or wear that indicate preferred methods of interaction with an object or environment" - UPoD
  • Reduce information fragmentation
  • Modularity - "A method of managing system complexity that involves dividing large systems into multiple, smaller self-contained systems" - UPoD
  • Building blocks != presentation
  • Hang signposts along the way
  • wayfinding
  • Example: breadcrumb navigation
  • In a linear guide set, add a link (system) to where to go next

---

My take away: when building navigation for your doc site, keep these ideas in mind:

• Use hierarchies to break down complexity
• Build navigation by category
• Include navigation elements within the content (sidebars and inline links)
• Use metadata content linking to make popular topics easier to access
• Reduce information fragmentation
• Make navigation easy and clear to use

Christy Lutz - You Have Already Succeeded: Design Critique Guidelines Make Feedback Easier

Presented by Christy Lutz

"Feedback makes you stronger."

Ask questions (to yourself or your teams) on how to ask, give, and deal with feedback.

Feedback leads to better working relationships.

Feedback works (it makes things better. Every time.)

What do you need to start using Design Critique Feedback:

• Identify stakeholders (including you)
• Create a scope statement

Write down feedback guidelines (ask for what you need)

How do you start?

• Just start
• Listen and repeat
• Anyone who tells you differently is selling something (you don't need to sell your work)

How do you get people involved?

• Throw a feedback party
• Utilizing stickers can be fun and creative resource

Schedule a design review

Gather feedback anywhere and everywhere

How do you give feedback?

• Criticism
  • passes judgement - Critique poses questions
  • finds fault - critique uncovers opportunity
  • is personal - critique is objective
  • is vague - critique is concrete
  • tears down - critique builds up
  • is egocentric - critique is altruistic
  • is adversarial - is cooperative
  • belittles the documenter/documentation - improves documentation
• You are a person

Tell me, how do you feel? Ask questions.

The goal of the project is the goal of your feedback. Your role is the Defender of the Goals

Defend yourself (defend the feedback to yourself)

How do you deal with feedback? A.K.A., how can I be feedback royalty?

• Build up an immunity
• You are not a documentation vending machine. You own it.

How do you measure your results

• Follow up on the things you don't understand
• Does this support the goals of the project?
• For some feedback, the answer is going to be "no"

Feedback is opportunity for discussion

How do you report your results

It's not about winning

Your goal is not about making everyone happy

Teach design critique guidelines to your team

---

My take away: Feedback is necessary to build better documentation and relationships with your [product] teams and is an opportunity for discussion.
Develop a feedback system that includes:

• Identifying stakeholders
• Defining the scope/goal(s)
• Setting guidelines
• Scheduling reviews
• Measuring results

Feedback is often you (the tech writer) just repeating back what you heard in your terms.

Getting people involved can vary from company to company but the common advice is to make it fun for everyone.

Know the difference between criticism and feedback (negative vs positive). Often time, feedback is little bit of a positive and negative experience (so build up an immunity).

Follow up on things you don't understand.

Testing: It's Not Just for Code Anymore

Presented by Lyzi Diamond

Testing your documentation is good (even if it is informal or formal).

Good documentation pays attention to the small things:

• Consistency
• Completeness
• Correctness
• Contributability

Without automated testing, their documentation would fail.

---

My take away: Reviewing and/or testing documentation for consistency, completeness, and correctness should be important to every doc writer. With formal (automated testing) or informal reviews, this can be achieved with ease (once a process has been set up).

Even Naming This Talk Is Hard

Presented by Ruthie BenDor

• All the good names are already taken
• Because the good names terms are already taken overloaded
• Because naming is reduction and we are bad at choosing what to exclude
• Because names evoke, and we are bad at anticipating that
• Blacklist and whitelist vs blocklist and allowlist - internal/social context awareness
• Because naming matters when even (especially when) we think it doesn't matter
• Why do bad names persists?
  • Because we don't realize they are bad
  • Because we recognize the name is bad but can't or won't justify fixing it
  • sentimental
  • humans hate change
  • overestimated cost of change
  • underestimating value of improved name (projection)
• What makes a name good or bad?
  • bad names
  • confuse, frustrate, misguide, obscure, and offend
  • good names
  • contextualize, explain, illuminate, and empower
• How can we name software better?
  • documentarians: let developers know when their names miss the mark
  • developers: writing software is an exercise in naming things

---

My take away: Naming software is often difficult for many reasons including:

• good name are already overloaded
• people are bad at [product] reduction
• names evoke thoughts and images (both good and bad)
• some people think it doesn't matter (but it does!)

Bad name persist because [product owners]:

• don't realize it's bad
• won't justify fixing it for many reason

bad names confuse, frustrate, misguide, obscure, and offend while good names contextualize, explain, illuminate, and empower

How can we name software better? Get everyone (tech writers and developers) together to have a discussion and go through a few writing/naming exercises.

Everyone's a Player (in a Mid-90s MUD)

Presented by Kenzie Woodbridge

There typically four player types: socializer, explorer, achiever, and killer
Document in game design should emphasis interactive over acting by helping facilities produce vague information and produce cryptic hints when players appear to be stuck
Ways to emphasize acting over interacting:

• Provide a manual
• Include auto-map and auto-log facilities

Socializers are natural documenter; they need your support

• Provide templates, assist with publishing, impose a structure and organization
• Advocate for them to others, Work to include them where they are excluded, give them public kudos

Explorers are anti-documentation; extract the info from them

• Documentation: shows off expertise, keeps icky users away (no pestering), is another thing to have knowledge of
• Reduce barriers (provide templates), rewrite the docs for the audience, help enforce expectation to look at docs first

Achievers are inconsistent documenter; turn it into a game for them

• To motivate achievers: post doc writing/review stats, make doc authors visible, advocate for docs as critical success criteria in projects
• Be available on short notice, provide and enforce templates, publicly thank them

Killers are inconsistent documenter and have an element of destructive chaos (power hoarder); get them to document something

• Self-protection strategies: keep discussions public, document everything (ironically), engage Explorers in the struggle
• Treat agreements like agreements, follow up, follow up again

---

My take: As a tech writer, you'll encounter and need to motivate four different personalities for the purpose of getting them motivated to contribute to the documentation base: socializer, explorer, achiever, and killer.

• Socializers are a natural documenter but they'll need your support. To keep them motivated, provide public kudos from time to time.
• Explorers are anti-documentation so you'll have to extract the information from them. To get them involved, show them the value of documentation and provide templates as a starting point.
• Achievers are inconsistent in their documentation efforts but you can turn that behavior around by turning it into a game. To keep the game lively for them, provide stats and reviews periodically, enforce templates (as necessary), and publicly thank them.
• Killers are inconsistent too but also are power hoarders and getting them to contribute will be very difficult. Employ a self-protection strategy by keeping discussions public, document everything, and treat agreements like agreements. Finally, follow up on your follow-ups.

Treating Documentation Like Code: A Practical Account

Presented by Jodie Putrino
How do we get there?

• Choose the right tools
• Automate
• Collaborate
• Define, then, design
• Adapt

"We're all doc writers now." Don't worry about grammar and spelling, I (the tech writer) will correct that.
Questions they had to answer prior to building, publishing, and implemented their documentation:

• Who are our users?
• What are they trying to do?
• How do they use/find our docs?
• What kinds of docs do we want/need to publish?
• Content reuse?
• What should the docs look like?
• How do we handle versions?
• How do we track usage?
• Can we get user feedback?
• When do we publish?
• How do we handle beta releases?

"The process is not the thing. It's always worthing asking, do we own the process or does the process own us?" - Jeff Bezos

---

My take: Treating document like code is good if your organization supports this process. To get there, choose the right tools, automation processes, and design.

Make everyone a doc writer and ensure them that you don't have to worry about the minute details (we the tech writers will fix it).

Ask your team the following questions when it comes time to implement, build, and publish documentation:

• Who are our users and what are they trying to do?
• How do they use/find our docs?
• What kinds of docs do we want/need to publish?
• Content reuse?
• What should the docs appear?
• How do we handle versions and track usage?
• Getting and using user feedback?

"The process is not the thing. It's always worthing asking, do we own the process or does the process own us?" - Jeff Bezos

Interviewing and Hiring Technical Writers: The Siberian Way

Presented by Sam Faktorovich

Necessary skills for a tech writer typically include:

• Some technical skills (CS fundamentals, OS knowledge, ability to read code)
• Capability and willingness to write documentation

Knowing how to write well != knowing how to teach others to write
One approach to grow your tech writer base is to high a non-technical writer and give them a two month crash course in CS (results may vary).
Pre-interview assignment task:
Write a medium size (1-2 pages) document describing a complex technical topic

• Topic defined by them
• ...? (missed the slide)
• Shouldn't mimic their typical day-to-day documents
• Should show candidate's capability to explain complex things

"Teach, don't tell" - Steve Losh
Tests:

• Easy: Explain the difference between HTTP and HTTPS
• Difficult: Explain the difference between UTF-8 and UTF-16

Other approaches to hiring tech writers

• Recruit your own developers?
• Grow the job market itself? This approached worked for them:
  • Teach tech writing class at one of the local universities
  • Public lectures promoting the profession
  • Technical writing bootcamps
  • Corporate consulting on setting up documentation dept/process

---

My take: Hiring a tech writer can be difficult if that field is lacking candidates. Do you teach a developer to write or a (non-tech) writer to learn how to read code? Both have their pros and cons. Teaching either candidate can be a painful training process if your company goes at it themselves but if you build a community around this need, it will could be a well rewarding experience for everyone.
Consider giving your candidates a writing test:

• Easy: Explain the difference between HTTP and HTTPS
• Difficult: Explain the difference between UTF-8 and UTF-16