Write the Docs Newsletter - December 2016¶
Seasons greetings and see you next year!¶
Hello, Write the Docs! As I’m writing this, there are gentle little fairy-snowflakes drifting past my window, and it’s triggering my instinct to hibernate something fierce. On that subject, this newsletter is going to take a brief hibernation period of its own over the holiday season. But never fear! We’ll be back in your inboxes once we’ve settled into 2017 a bit.
To tide y’all over, we have a nice hefty issue for you this month. From hiring practices to API resources, readability guidelines to UX testing, the community was — per usual — engaged on a broad range of topics. We hope you find something below to intrigue or inform. Have a great end of the year, and we’ll see you in the next!
NOTE: Remember, we’ll be keeping an eye on the #general channel for newsletter content, but if you see a conversation elsewhere on Slack (or Twitter or wherever) that you think is a good fit, ping our editor, Kelly O’Brien (@kobrien042).
Simplifying and tightening your writing¶
One of our most involved discussions this month was about limiting the length of sentences and paragraphs, with the goal of avoiding the “wall-of-text” effect and increasing the likelihood that customers will read your documentation. Here’s some of the general guidance that folks shared:
- Simplify by removing as many unnecessary words as possible
- Use plain language
- Consider whether punctuation like commas and semi-colons might mean that you’re stringing together too many phrases in one sentence
- Follow strict per-sentence word limits (participants specifically mentioned 28 and 25 words, and one commenter suggested this thoughtful GOV.UK blog post with even more tips for writing clearly)
Participants mentioned quite a few tools to use for refining your writing, from style handbooks to web-based readability tests. Although folks paid respect to Strunk and White’s Elements of Style, many said there are better options…specifically Richard Lanham’s Revising Prose, Garner’s Modern American Usage, and The Harbrace College Handbook (which now seems to go by The Hodges Harbrace Handbook). And check out this Write the Docs Forum thread for more style handbook recommendations.
One participant suggested this neat tool for trimming your writing. Others mentioned using Flesch-Kincaid scoring, tools like the Readability Calculator by Online Utility, and linters like Write Good for Atom to help improve readability.
The discussion wrapped up with a 74-word sentence quoted from Emma by Jane Austen:
“It was some comfort to him that many inquiries after himself and Miss Woodhouse (for his neighbours knew that he loved to be inquired after), as well as Miss Smith, were coming in during the rest of the day; and he had the pleasure of returning for answer, that they were all very indifferent—which, though not exactly true, for she was perfectly well, and Harriet not much otherwise, Emma would not interfere with.”
For those keeping score at home, that includes seven commas, one semi-colon, a parenthetical, and an em dash. If you’re curious, the sentence’s Flesch-Kincaid grade level is 15.4!
Hiring for technical background¶
An interesting hiring question arose this month about how to word a job listing when you’re looking for a particularly technical tech writer. It’s common to see “previous developer experience” listed as a requirement, but depending on what you’ll be expecting the writer to cover, it might be that what you really need is someone who comes from a system or database administrator background.
Part of the reason this crops up so often is that the listings are often assembled by non-technical recruiters who don’t always have a solid grasp on the different technical disciplines out there. So what can we do to make sure new hires show up on their first day with the technical background we’re hoping for?
There were lots of useful suggestions, most of which boiled down to: Consider your docs’ audience, and choose your words carefully. If your docs are aimed at helping people code, then probably that “previous developer experience” is a good way to go, preferably with details on the specific languages/environments they’ll be writing about. But if your documentation is more focused on configuration and/or optimization, then having a writer with “sysadmin or DBA experience” may serve you better. If your docs are broader-ranging, you can cast a wide net by asking for “technical background”, then focus it down in the interview process with a technical test (in addition to or instead of a writing test).
Running UX tests on your documentation¶
Knowing where your docs are falling down on the job is a critical first step to being able to improve them. So what can you do to determine where (and with a little luck, why) your documentation isn’t working for your readers? Simple. Test it.
User experience testing (UX testing, usability testing, etc.) can be just as helpful for testing the effectiveness of your docs as it is for determining the intuitiveness of your product. When it came up in the Slack channel this month, there were lots of great ideas for how to apply UX testing principles to documentation.
First off, whether you’re testing your product or your docs, the principles are the same – give your users (in this case your readers) some concrete examples to work through, observe their behavior and then give them an opportunity to voice their thoughts on their pain points.
Second, you don’t necessarily have to separate your product testing from your docs testing. Oftentimes, if you give your users a open-ended task to perform, you can get great insights just by watching where they go to get information and when they get stuck. (And whether that information gets them unstuck or not.)
This blog post from the Nielsen Norman Group was put forth as a good resource, when you’re designing tasks for user testing. And if you’ve got tasks in mind, but you’re looking for tools that will let you capture user feedback, here’s a substantial and relatively current round-up of some of the products out there.
Want to help make 2017 the Year of the Doc?¶
Okay, so we don’t really have a spiffy catchphrase, but we’d still love your help making next year Write the Docs’ best yet! We’re just starting to gear up for Write the Docs North America — in Portland, as usual, from May 14-16 — and the organizing team would love some help! If you’ve ever thought about running your own Write the Docs event, this is an excellent way to see how they come together, first-hand! If you’re interested in volunteering, have a look our event roles and drop us an email!
And of course, if you just can’t wait that long, or you’d rather focus your efforts locally, it’s always worth looking up the nearest meetup (or starting one if it’s too far away!)
