Home »

Write the Docs Newsletter – November 2020¶

Hello friends! It’s Beth and the newsletter team here, writing to you after our second ever online WTD conference. I spent the days after Prague feeling a strange mix of revived and exhausted - in other words, just how I always feel after a Write the Docs conference. A pretty good outcome if you ask me. If you’d like to catch up on anything you missed, or rewatch your favourites, videos of both the main stage talks and lightning talks are now up on our YouTube playlist. Enjoy!

If you’re already looking forward to the next conference, we’ve got you covered: tickets for the Australia & India conference on 3-4 December are on sale. To get a sense of the great stuff you can expect there, check out the list of speakers.

One last thing - the salary survey is open until 16 November. So if you’ve been putting it off for later, please do fill it out - it only takes 5-10 minutes. And we’d love it if you sent the link to documentarian colleagues, friends or contacts outside the WTD community, who might not have heard about it. The more data we have, the more useful it becomes, so we’d like to hear from as many folks as possible.

That’s all the news I’ve got for you today. Onto the articles from our lovely correspondents!

Career progression among documentarians¶

What does a typical documentarian career ladder look like? A theoretical standard is something like Junior Technical Writer > Technical Writer > Senior Technical Writer > Documentation Manager - but reality can be much more complicated. This month, we learned about how the docs career path varies from company to company and other roles that tech writers might jump into.

About those job titles…they can be pretty different between companies! For the junior role, some companies use “Associate” or “Writer I”. Some companies have more variety at the more experienced end of the spectrum, where a senior might be a Staff Technical Writer, a Technical Writing Specialist, or Principal Technical Writer. And still others may have parallel roles like Technical Editor; or an entirely separate track for lead/management positions.

Methods for moving along the career ladder also vary by company. Some places might emphasize developing new technical skills, and others might be more concerned with the impact you can create. For a comparison of skills- and impact-based approaches, check out this presentation from our very own newsletter editor: Models for personal growth: career progression for tech writers.

Different paths into documentation as a profession is a common topic in our Slack discussions. Perhaps less common is where technical writing can lead you. Some of the roles people mentioned to transition out of technical writing included product management and project management, software development, training, data science, business analysis, customer support, and (for a really adventurous change) operating a guesthouse in France! Deborah Barnard’s blog post After tech writing: where do you go if you want to move on? may be helpful if you’re considering a change.

If you’re considering a managerial position but your company doesn’t offer a documentation-oriented job with managerial duties, you could try to write your own job description (especially if you’re currently performing those tasks without the title), and persuade your company to create that job. For more on moving into management, these resources might give you more information about what to expect:

The book Managing Writers: A Real World Guide to Managing Technical Documentation by Richard L. Hamilton
Advice at the Ask a Manager website
Simon Sinek’s talk Leadership is a learnable skill
The Manager Tools and Career Tools podcasts

All about accessibility and inclusivity¶

Over the years, the Write the Docs community has given plenty of attention to inclusive and accessible documentation: it’s a topic that’s close to our hearts. And recently there’s been a ton of great discussion and sharing of resources - so we thought it was time for a round-up of useful links.

First off, a community member with few resources to develop accessible doc pages asked about accessibility widgets. While accessibility widgets can be an attractive option, it turns out they should be used with caution (just like pretty much every tool!). Keep usability at the top of your mind – accessibility achieved just through integrating a widget, or by following a checklist, can produce a less usable web experience. For more in depth on the proceed-with-caution side, see Even custom overlays have questionable value; and a bit more on the pro side, with solid explanation of the general issues: Accessibility Overlays in Digital Content.

To learn more about creating accessible websites:

A website that lets you test for accessibility components on web pages, Accessibility Support
The Web Accessibility Initiative
The POUR principles for creating a truly accessible website (Perceivable, Operable, Understandable, Robust)

For those who want a deeper dive:

Certification requirements from the International Association of Accessibility Professionals
Introduction to Web Accessibility from edX
The Paciello Group, an accessibility consulting firm, provide services and resources
Classes from Deque, another accessibility consulting firm

For a real-world tale of why accessibility matters, see 5 most annoying website features I face as a blind person every single day.

Those of us who document APIs should consider that API Document Generators Can Fall Woefully Short on Meeting Accessibility Guidelines. The article is three years old, but the problem remains, although one WTDer called out ReDoc as a good option for its attention to accessibility issues.

Members of the community also gave shoutouts to resources for bias-free language:

Bias-Free Language in the APA Style Guide
Terminology, Power and Oppressive Language, a draft standard from the IETF

Finally, a few handy WTD resources: lists of resources for inclusive writing and accessibility tooling, plus some relevant conference talks and writeups in newsletters.

Dealing with stress & struggling to write¶

Is it any surprise that we’ve been talking a lot about stress recently? Truly working out how to deal with stress is so individual, and means looking at the big picture - it’s not something that you can sort out with one or two quick tips. But our community members recently shared some thoughts on how they manage stress, especially when that stress causes you to struggle to focus and complete work. Maybe you’ll find some of them helpful.

If you’re feeling overwhelmed by the weight of your to-do list, perhaps you can explicitly ignore/say no to some work. Can you postpone or drop lower-priority tasks? Or can you ignore them even for a day - just pick one item from your list, and try to complete that? Sometimes finishing one thing can feel like a big win.
Collaborate! Your colleagues might be able to help - can you find ways to delegate, or share the load?
Recognise when something might be good enough for now. When you have a completed draft, send it out for some feedback, even if it isn’t perfect.
Take a step back, and intentionally move through each step of the writing process. How would you advise a beginner to work through a task?
It’s not always easy, but are you looking after yourself? Adequate sleep and nutrition won’t fix everything, but they are the solid foundation that we humans need.
For feeling overwhelmed in the moment, recognise that you’re just not gonna get any work done, and take the break you need. Some people find meditation and/or breathing exercises helpful; other people choose exercise - even if just a few minutes. (My personal favourite? Lie down and take a proper nap - Ed.)