Write the Docs Newsletter - September 2016¶
Welcome to the Write the Docs Newsletter¶
Hello Write the Docs! If you’re getting this email, you’ve probably attended (or considered attending) one of the documentation conferences we’ve put on over the last few years. As our events have grown, so too has our community, and we’re working hard to make Write the Docs a year-round affair.
As part of that effort, we’re sending you this, our inaugural edition of the new Write the Docs monthly newsletter! Our goal is to make it easier for folks to keep current with what the community’s talking about each month. The bulk of the newsletter content will be distilled from interesting conversations that crop up on the #general channel of the Write the Docs Slack . We’ll be highlighting topics that are recurring themes or simply seem to resonate with a lot of folks.
Note
We know the #general channel is just one arena for docs talk. If you see a conversation elsewhere on Slack (or Twitter or wherever) that would make good newsletter fodder, ping our editor, Kelly O’Brien.
And without further ado, here’s a few topics of conversation from this past month that tickled our fancy:
What to include in your UI copy¶
Deciding what to include in your UI copy — and what not to — always takes some careful thought. When do you try include full definitions or descriptions right on the screen, and when is it better to simply add a link off to more comprehensive documentation?
The general consensus was that the comfort level of your audience has a big impact on how much explanation to put in UI. If you’re writing for an audience that’s easily daunted or confused, include as much explanation as possible. On the other hand, if your audience includes experienced users who may need only reminders, the UI text could be reminders only, with a link to the extended documentation.
There were also a handful of great suggestions for UI copy best practices:
- Progressive disclosure: Show key points that are likely to be broadly useful or the most critical, and make more information available on demand, for example with a hide/show control or a link to extended documentation.
- Simplify the item that needs explanation, if possible, so that it requires less explanation.
- Keep in mind that too much in-UI help and information can overload users and reduce readability.
- User feedback through support requests and user testing can help writers find the balance of detail and explanation that is “just right” for most users.
If you’re looking for more info about UI help text, check out Beth Aitman’s talk on the subject from Write the Docs EU 2015. For more on progressive disclosure, try this blog post: Masking Complexity through Progressive Disclosure,
Metrics case study: Total Time Reading (TTR)¶
Who doesn’t love talking about documentation metrics? (No one, that’s who.) One of the Write the Docs co-founders, Troy Howard, has a new blog post out, in which he takes a close look at Total Time Reading (TTR) as a way of judging the success of a page or article. If documentation metrics is your thing, it’s definitely worth a read: TechDocs Metrics Case Study: Total Time Reading (TTR)
Code review versus copy review¶
Another blog post that spurred conversation was this one from the Atlassian blog, The (written) unwritten guide to pull requests. In addition to having lots of good pointers for, y’know, doing code reviews, it also sparked a conversation about some of those same techniques can be used to conduct copy reviews on your docs.
This especially struck a chord with folks who work with a team of content contributors. Having a set editorial review process is really helpful for building up a reliable and transparent workflow. The general feeling was that stealing some code review techniques and adapting them to an editorial review process could save you from having to reinvent the wheel.
Another suggestion for a good resource when you’re building up copy review processes was ‘The Checklist Manifesto’, by Atul Gawande.
One style guide or two?¶
When it comes to content style guides, there was some discussion of whether it was better to have separate guides — one for docs and one for marketing content, for example — or to try to cover both types of writing with a single guide. There were lots of opinions.
Here are some thoughts from proponents of multiple style guides:
- Technical documentation and marketing have different goals, so a single tone/voice may not be appropriate for both.
- Accepted conventions in one group may be rejected by other groups (for example, using sentence case in headings).
- Some groups, like marketing, typically use a casual voice and flashy word choices that aren’t always appropriate in technical documentation.
From the other camp, here were some arguments in favor of a single guide:
- Customers may be confused by differing and conflicting terminology in company materials when groups use different style guides. For example, is it an app, platform, product, service, or something else?
- A consistent voice across all company materials is a trend, even if, historically, technical docs may not have been beholden to the brand’s tone guidelines.
- Using terms that a layperson will understand is best practice in tech docs, and having a central style guide makes that consistency easier.
For more on documentation style guides, this blog post from I Heart Technical Writing is a good place to start.
Looking for more Write the Docs?¶
We hope you enjoyed our first installment of Write the Docs hot topics! Keep an eye here every month for more. But just in case this wasn’t not enough docs love for you:
- We feel ya.
- Scope out our upcoming conferences! (The next one, in Prague, is coming up in a few weeks!)
- See if there’s a Write the Docs meetup near you! (And if there’s not, think about starting one up!
