Home »

Write the Docs Newsletter - March 2017

Winter is coming – to an end!

Hello, Write the Docs! Obviously, the end of the cold season depends entirely on what coast (or continent) you’re on, but here in the western US, we’re rapidly approaching springtime – which means Write the Docs North America is right around the corner!

This month’s newsletter is a little behind schedule (apologies!) because we were holding out so we could include details about this year’s awesome speaker lineup for North America! We’re also excited to announce ticket sales for the EU conference, as well as an updated version of our community Code of Conduct (more details on both, at the end of the newsletter). It’s been a big month for WtD events!

We’ve also had one of our most active months on the community Slack channel! We’ve cleared 1500 members, and we’re to the point where there’s almost always something going on, pretty much 24/7. Thanks to all of you for making this community so engaged and lively!

As a result, we’ve got another great issue for you, packed with distilled conversations from around the Slack-iverse. Hope you find something to intrigue or inspire!

North America conference speakers announced!

In the last few weeks, the conference organizers have been faced with the hardest part of their jobs: selecting fewer than 20 talks from the 100+ submissions that came in. The quality of the proposals this year was incredible. To everyone who submitted a proposal – THANK YOU. We wouldn’t have a conference without your passion and hard work.

We’re really excited about the lineup we’ll be bringing to the Crystal Ballroom stage in May. Topics range information architecture in API documentation to injecting empathy into your error messages, from writing docs at a startup to using game design techniques to manage interpersonal conflicts in your teams. You can read more about the full talk lineup here: https://www.writethedocs.org/conf/na/2017/news/announcing-presentations/

Know the rules for formatting procedures – and when to break them

An interesting question came up this month about how to introduce a procedure, i.e., a list of numbered steps. Some style guides (ahem, IBM) require writers to use a lead-in sentence, a heading that includes the word “Procedure,” or some combination of the two. The question was: Are there good reasons to disobey this rule? The community’s answer: Yes!

One person mentioned that adding “Procedure for” to the beginning of every heading makes documents harder for readers to scan. Another pointed out that headings and lead-in sentences are often redundant and said they’ve successfully used brief, descriptive headings with no lead-in when formatting procedures.

Others felt that it’s important to have a short description immediately after the heading to provide context and help readers understand the what and why of the procedure. This format eliminates redundancy between headings and lead-in sentences and avoids the sparse tone of going straight from the heading into a list of numbered steps.

Overall, folks agreed that the format that uses the fewest extra words and helps readers find the information they need is the best format.

Should documentation have bylines?

A lively discussion about bylines in technical documentation showed up in the #watercooler channel this month, with some documentarians shuddering at the thought and others seeing it as appropriate acknowledgment. Some folks saw lack of bylines as a sign of corporate appropriation (for legal or intellectual property reasons), while others saw it as recognition that tech docs are often highly collaborative and therefore difficult to attribute to a single author. Still others saw bylines as an opportunity to encourage personal interaction with customers, while yet another group saw that same interaction as intrusive.

Overall it seems that attitudes toward bylines really depend on context – as any good doc issue should! Bylines can help create a sense of community in developer docs, for example, or for community-driven projects, while for enterprise-scale doc sets they can be less appropriate. And book authors are in a category of their own, authorship being something that’s far less often repudiated or denied – after all, we have at least two noted authors of software books among us, both of whom helped dispel some common assumptions about the fame and fortune that accrue to book deals in the real world.

Resources and best practices for alt text

Ensuring the accessibility of our content is at once super-important and a perennial challenge. Adding alt text for the visual aspects of our documentation is a good place to start. A request for some resources for crafting alt text arose this month, and there were some useful responses that we thought were worth sharing.

As a rule of thumb, this what one member of the community suggested, when considering what to put in your alt text: “Ask yourself what someone would need to know if they couldn’t see the image.” For more detailed guidance, there were a few links that floated to the surface:

Studies in comparative job titles

Every once a while, discussion in the WtD Slack turns to titles…job titles, that is. This month, some of us shared our actual job titles and some dream job titles.

Actual titles included:

  • Information Coordinator
  • Self-Service Content Manager
  • Manager, Docs and Community
  • Word Writin’ Guy (yep, it was on his business card!)

Dream titles ranged from meaningful to fanciful:

  • User Docs Lead or Dev Docs Lead
  • Knowledge Management Coordinator
  • Verbiage Engineer
  • Prose Technician
  • Word Scientist
  • Lord High Admiral of User Documentation

Some folks pointed out that all the variation in documentarian job titles makes it hard to figure out who does what. And the standard “Technical Writer” seems to get more hits on LinkedIn. Still, who wouldn’t want to be The White Wizard of Help? As one person pointed out, Gandalf insisted on reading the documentation!

Other exciting community developments

As we mentioned up top, there’s been a ton of exciting developments across the community this month. Here’s the details on a few of them:

Thanks for reading, and see you again next month!

New and Improved Community Code of Conduct   Write the Docs Newsletter - April 2017