Home »

Write the Docs Newsletter – June 2018¶

Hi folks! Kelly O. here with the last issue of the newsletter until August. (In the meantime, the editorial team will be taking a wee summer break!) It’s been an exciting spring, with another successful Portland conference under our belts, and a jam-packed rest of the year laid out ahead of us!

As a quick refresher, here’s what’s on the docket:

August 18-22 – Write the Docs + Open Help – Cincinnati, Ohio, USA Submit a talk by next Monday, June 18 or buy a ticket any time!

September 9-11 – Write the Docs Prague – Prague, Czech Republic Speakers will be announced soon, and in the meantime, you can get your tickets here!

November 15-16 – Write the Docs Australia – Melbourne, Australia Get your talk proposal in by July 20th and snag your ticket early, so you can start planning your visit!

If you’re interested in a more virtual way to engage with the community, you could also think about volunteering to help out with the year-round organization. When we come back in August, we’ll be putting out a call for volunteers to help both with the newsletter team as well as a few other working groups. So have a think about whether and how you might want to pitch in.

One other quick thing to note was an interesting tidbit from the #meta channel about the pros and cons of Slack’s message limit. Since it’s a topic that comes up on a relatively regular basis, we thought it’d be worth addressing here. Essentially, while it can be frustrating to see valuable conversations and resources swallowed by the Slack-void, the message limit helps foster a more comfortable space for community conversation, without the looming knowledge that every word you write will be preserved, publicly, for all time.

We do try to offset the transience of the Slack discourse at large with this here newsletter, where we capture a handful of pithy conversations each month. Speaking of which, let’s get to ‘em!

Helping your project managers understand docs¶

Many of us have been in the debatably enviable position of being a company’s first docs person. In such situations, it’s critical to get your teammates, especially project managers and the like, to understand both what you do and what you need in order to work effectively.

So in this situation, someone asked on Slack this month, what are the top things you’d want to communicate to your PM to help them understand your role?

The community came back with some great suggestions, as usual:

Process definition. Docs processes are often new to non-docs folks, so they’re a useful place to start. Share how new content gets defined, created, and reviewed; how ongoing changes are batched and implemented; and how your publishing flow works, step-by-step.
Content = product. The sooner you can get your team to start thinking about the docs as part of the product and not as some separate thing, the better. It will make it much easier to integrate your docs cycle with the broader product cycle.
Getting in on the planning. Speaking of which, impress upon your team the value of involving you at the planning stages of the cycle. So much of what docs folks can contribute to a product happens long before anything gets built. Plus, being present for the scoping conversations is necessary if you want to be able to manage your workload effectively.
Timeline management. Explain that docs take time. If your ship date is the end of week six, that means there needs to be a (mostly) working version available by, say, the Tuesday of week four… not the Thursday of week six. Being explicit about your scheduling expectations can save you a lot of future headaches.

For an example of someone trying to explain the value of technical communication to folks who are new to it, this LinkedIn post highlights some interesting assumptions and pain points that might be worth thinking about.

If you’re a lone docs person and still working on communicating this stuff to your team, pop into #lone-writer to talk with folks who are/have been in your shoes.

Junior vs. senior technical writers¶

A common theme in WTD career discussions is that the path into or through a documentation career is rarely straightforward. There are benefits to that, in terms of flexibility and a wide-ranging understanding of what documentarians actually do, day-to-day. But one of the drawbacks is that it can be difficult to see a clear path for advancement, even in more traditional ‘tech comm’ positions. This month, that topic was raised in the context of defining what constituted a Senior Technical Writer role versus a Junior Technical Writer?

Our crowd of documentarians came up with three primary distinctions between the two (title aside, of course):

Amount and type of experience
Level of supervision required (or amount of supervision you’re providing to others)
Degree and scope of non-writing responsibilities

Senior writers would typically have more experience and require less supervision than junior writers. The senior writer may also be managing a team, having a junior writer produce docs, while the senior writer focuses on high-level planning, project management, and tooling decisions. However, some of these distinctions are only a helpful for teams of multiple writers. For the lone writer, the key to advancing from junior to senior may lie in mastering certain skills (writing, tools, and technical competencies), collaborating cross-functionally on bigger projects, or developing specific expertise within the industry your company serves.

If you’re struggling to define or move along your own career path, head on over to #career-advice where you’ll find a wealth of constructive advice.

Short advice for writing error messages¶

This month, the hivemind fielded a request for advice about writing good error messages. Attached to the request, though, was a familiar (and vital) caveat: They needed short, easy-to-digest pointers, rather than longer, meatier reads, in an effort to boost the odds that their developer teams would actually find the time to read what they shared.

One of the top suggestions was Kate Voss’s Error Messages talk at WtD Portland 2017 We’ll admit that a 15-minute video doesn’t fit the “short” parameter…but Kate’s own distillation of her talk brings it down to three concise rules: Humble, Helpful, and Human.

Humble: apologize and acknowledge the error
Helpful: make sure the error message tells users what to do next
Human: use plain language that any user will understand

Here’s a roundup of other links that were mentioned:

How to Write a Perfect Error Message by Vitaly Dulenko
Apple’s Providing User Feedback
Non-Fatal Errors: Creating Usable, Effective Error Messages by Emily Wilska
Klariti.com’s A Review of Error Messages
Message Text and User Interface Text: Is it OK, Now? by Rahul Mehrotra
Windows Dev Center’s Messages

For other style or mechanics questions, the #general channel is full of helpful documentarians ready with guidance.

Job Board: Your ad here¶

Although the newsletter is taking a summer break, the Write the Docs job board isn’t going anywhere! Create an employer profile and post your open positions to get them in front of thousands of docs folk all around the world. Any jobs posted as a ‘featured’ listing will be included in next newsletter, in early August.