Write The Docs 2019

The following is a summary of some of the presentations I attended and enjoyed.

Draw the Docs presented by Alicja Raszkowska was interesting as she advocated for using more graphics (particularly cartoons) in technical documentation. While I enjoy the notion of this, one must know their audience before they can start adding cartoons to illustrate their product and/or points. She is also developing a tool called mermaid that creates visual content similar to Visio but with custom images and markdown input.

Sarah Moir's presentation called "Just Add Data: Make it easier to prioritize your documentation" makes a good case for using analytics and other feedback to sort out prioritization of which documents should get the tech writer's attention.

Matt Reiner gave a very energetic presentation called "Show Me the Money: How to Get Your Docs the Love and Support They Deserve" which outlines how to make a business case for getting more resources for documentation. In Matt's presentation, he provides a good and detailed method for creating a business case and how to pitch it to management. I believe this is a good resource for all tech writers!

"How to edit other people's content without pissing them off" by Ingrid Towey was an interesting presentation on editing other people's content. The four principles are as follows: Assure that the content originator that we are all on the same side, when editing content, it's an edit and not an edict, explain why you're editing their content (preferable before you do it), and get help when thinks don't go smoothly. Good idea if one isn't already applying this.

Kathleen Juell's "Writer? Editor? Teacher?" presentation basically provided parallels to how tech writers can leverage teaching philosophy (particular college level) to technical writing. The topics she covered was basic documentation layout, design, and goals, providing templates, peer editing/reviews, and writing like as a teacher or an editor (clarify, explain, and goals). As a former college teacher myself, I see the lines between a teacher and tech write to be very blurry.

Shannon Crabill provided some thoughts and guidelines for how to manage documentation for an open source project in her talk called "Documenting for Open Source". Some tips include avoid assuming the technical knowledge of your readers (one should include a requirements section in your guides as to not lead on the readers who may get frustrated layer in the document when they discover they cannot complete it), README files are required, how to get users started, provide yourself or your team with templates (to avoid issues like duplicate PRs), and always provide links to any and all resources.

Heather Stenson provided some thoughts on how to get non-writers to contribute to documentation in a presentation called "Any friend of the docs is a friend of mine: Cultivating a community of documentation advocates". She defined who "friends of docs" are (those who write but are not technical writers), the different levels of friends of docs, how to get people to contribute more, strategies to find, support, communicate, and provide feedback to these friends, how to overcome obstacles friends of docs may encounter, and how to continue building this doc-friendly culture.

Chris Bush gave a dry-humor filled presentation called "SDK Reference Manuals: A flow-based approach". Overall it was dry but reassured that the process for creating, maintaining, and updating SDK docs haven't really changed all that much in years.

This conference also live-streamed and posted all their presenters on this YouTube playlist: https://www.youtube.com/playlist?list=PLZAeFn6dfHpmuHCu5qsIkmp9H5jFD-xq-

Write the Docs Newsletter – November 2017

Little late on catching up with my Write the Docs newsletter but November 2017 offered some good tips:

Worth it: images & screenshots

This month, we had a couple of conversations about images and screenshots that raised some interesting questions. When do we need to include images in our documentation? How many images is enough? How many is too many? Given how difficult they can be to maintain, are they even worth it?

Of course, our community of documentarians had a variety of good answers to share. For starters, there was a consensus that screenshots are inherently challenging. They take a significant time commitment to maintain, especially for a product with frequent UI changes. It was also pointed out that they are often overused and may not even be that useful to our readers. Diagrams, on the other hand, can be incredibly useful when designed well. Overall, the feeling was that using some screenshots and other images in your documentation is usually worth it, especially if you can commit some bandwidth to maintaining them.

Some other image tips that came up included:

• Crop your screenshots to highlight only the specific area of interface you're documenting.
• Keep all of your image files in a single, separate location. If possible, use version control.
• Develop – and stick to – a standard for producing screenshots: size, tool, resolution, file type, etc.
• Triage your updates. Prioritize functional UI changes over changes in button color, for example.

A {} by any other name

Sometimes, when scanning Slack, it's easy to spot which comments are going turn into newsletter fodder. Other times, a trivial comment will unexpectedly blow up. This month, what started as a quick 'hey, what's the name for this punctuation mark?' turned into a surprisingly in-depth and entertaining discourse.

For many of us, our primary use of {}, [], and () is in code. But what you might not know is that a) there is a dizzying array of names for these marks and b) when using them in prose, they have some interesting uses you might not be familiar with.

Just in our own Slack community, people said they refer to {} as squiggly brackets, braces, curly brackets, curly braces, and (totally seriously, I'm sure) curly wurly woos. If that's not enough, the wikipedia article on brackets is not only a hilariously deep rabbit hole, but also provides us with more names including: French brackets, definite brackets, swirly brackets, birdie brackets, Scottish brackets, squirrelly brackets, gullwings, seagulls, twirly brackets, Tuborg brackets (DK), accolades (NL), pointy brackets, third brackets, fancy brackets, and m braces.

As for their use in prose, as opposed to code, someone shared a Grammar Girl article, which digs into the various proper usages for () and []. (Curly wurly woos don't come up much in prose, so the post doesn't touch on them much.)

So remember, for the Write the Docs hivemind, there is no question too big, and no question too small.

It's your turn to ask the questions

We've all fretted over what we might be asked during an interview. But what about when it's our turn to ask questions? This month, a job-hunter sparked a great conversation about what to ask in an tech writing interview. We've written up a few highlights:

Show them you know your job. Asking specific questions about their expectations and processes can get you into the nitty-gritty, and give you a chance to show off your chops. This blog post has some good examples.

Don't be afraid to follow up. If something they say raises a concern – or just piques your curiosity – loop back to it when your turn for questions comes.

Ask what they think of your resume. Directly asking about your application materials gives the interviewer a chance to ask about your background, and you a chance to clarify or crow about your previous roles.

Have a couple backups. Some of your questions will be answered in the course of the interview, so come prepared with spares.

Clarify next steps. When the interview is wrapping up, make sure to ask when you can expect to hear from them. If they don't give you a firm date, tell them you'll follow up in a week.

The bottom line is to remember that you're asking questions to help you figure out whether the job is a good fit for you too.

To automate, or not to automate

One Slack contributor's triumphant story of automation success sparked a thoughtful series of posts about when and how to automate routine tasks – and when not to. We had a cautionary tale of an elaborate automated doc toolchain that couldn't be maintained after its creator left the company, nice distinctions between personal productivity hacks and automation for a larger group, and meditations on automation ROI. Here are some key takeaways:

• Automate all you like if it's just about your own work - whether it's email routing rules, keyboard shortcuts, or any other professional task for which you're solely responsible.
• Think more carefully about ROI and usability if you want to automate shared work. By all means automate routine and time-consuming tasks ("barnacle scraping" as one writer put it). But the cost:benefit ratio might not be worth it when it comes to one-off tasks. (This goes for personal automation too.)
• When considering an automation, consider not just the time and tedium saved, but also what it might take to make automation usable for more people. Make sure, too, that you're not threatening someone's job by taking away a manual process they're committed to or depend on.
• Remember that automation can help reduce errors, too.

Write the Docs Newsletter – October 2017

http://www.writethedocs.org/blog/newsletter-october-2017/
This month's post includes the following topics:

• Putting our URLs to work – for us and our readers
• The true meaning of “API”
• Proofreading and copyediting your own work
• Defining developer relations/evangelism/advocacy

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