Home »

Write the Docs Newsletter – July 2022¶

Hi everyone. Aaron and the newsletter team checking in and hoping all is well for you.

Job security and transitions was a topic on lots of people’s minds this month. Some people have been discussing how the Slack community has been a big help to them. Several members have been using it for networking, which helped them find new jobs after layoffs.

In related news, the 2021 Salary Survey has been released. It’s based on responses from 959 documentarians (887 employees and 72 independent contractors) from 49 different countries. This year for the first time, we were able to break down median salary by years of experience, gender identity, and organization size. We hope you can find something useful for you in your own salary discussions. And look out for the 2022 survey, which will be opened up for responses later this year.

We hope the post-solstice time, whether summer or winter, is treating you well and we’ll be back with more news in September following a one-month break.

What’s in a good reviewer’s guide?¶

Getting useful technical feedback is challenging for many documentarians. “Publish and wait for the corrections to flood in” may be a time-tested tactic, but it’s no match for publishing accurate docs to start with! We can’t assume that subject matter experts (SMEs) automatically know how to deliver helpful reviews, so create a reviewer’s guide to support your reviewers in providing better feedback and get more productive comments and critiques.

A good reviewer’s guide should include information such as the review methodology, tools and features to use, tips for reviewers, the review scheduling process, coordination with documentarians and other SMEs, and references to additional resources such as style guides. Although it may make sense to add a reviewer’s guide to your style guide, they don’t have the same purpose: reviews should focus on content rather than form. Likewise, try to promote more substantial technical comments over grammatical reviews.

Your guide might also provide prompts for certain feedback types or questions for reviewers to ask themselves. Prompts such as “Include the ‘why’ in your comments” encourage reviewers to provide context and background information. General questions such as “What is the author trying to do?”, “Did they succeed?”, and “Was it worth doing?” can help reviewers get started. You can even add questions for reviewers to answer directly, such as “Does the procedure work as written?” Listing questions means more work when writing the guide, but helps you avoid getting only minimal or subjective feedback.

For more insights to develop a good reviewer’s guide, check out these resources:

The Art of the Review by Swapnil Ogale
Tech Doc: Unbearable lightness of peer-reviewing by Kristian Klima
conventional:comments by Paul Slaughter
08: Technical Editing (chapter in Open Technical Communication) by Jonathan Arnett

And another thing! Referring to other documents¶

After a workshop on accessibility at Write the Docs Portland, there was a discussion on one particular point of language: how to point the reader to a different heading or topic.

The first option, “see”, has plenty of advocates. It’s a short, simple word and we generally prefer simple language. It’s pretty general and doesn’t prescribe how you should be using the linked resource (unlike, for example, “read”). “See” is favored by the 2011 IBM Style Guide and the Google dev docs style guide.

But “see” has some downsides: it doesn’t apply to folks with visual impairments and its vagueness can make it hard to translate correctly.

The next contender is “refer”. Per the ASD-STE100 Simplified Technical English specification, refer is more correct: it means “to tell a person where to find information/give information,” while see is litera_lly “to know with the eyes.”

This specification has other more precise options to replace “see” in other contexts. For example, instead of “move the tube to see if the connection is tight” use “move the tube to make sure the connection is tight”.

There’s no clear winner here – all our options have compelling pros and cons! However, if you’re working on improving accessibility, a sure bet is to have high-quality link text – for example, using detailed text rather than “Read more” or “Click here”.

To dive deeper into this topic, please do see/refer to/examine/peruse Alexandra White’s and Carolyn Stransky’s talks about accessibility.

Certifications and qualifications¶

It can be hard to decide which certification or qualification you need to land a technical writing job. Even more challenging is knowing which ones are the most valuable. First, realize that, regardless of industry, experience is highly valued. But if you’re transferring to technical writing without immediately transferrable skills, other resume boosters are available that may help you appear more marketable. For example, accredited universities such as the University of San Diego and the University of Washington have online certification programs in technical writing that offer a comprehensive and fundamental overview.

If you’re looking for more specialized authoring skills, tools and domain qualifications may be more useful. DITA, HTML, CSS, JavaScript, Git, AWS, and Kubernetes are a few you can explore. Overall, obtaining sought-after foundational and technical skills can make you more competitive and help you better grasp common methodologies and tools.

Although certifications are helpful, they are not a magic key to qualifying you for every technical writing position. Hands-on experience is usually preferable, so seek opportunities where you can contribute to documentation or write and publish blog posts, articles, or other instructional materials. Then, with all your work, create a portfolio, and include a link to it in your resume. The most important thing is not to give up! Because there are many paths to becoming a technical writer, yours may look very different from someone else’s. The key is to persevere and overcome the challenges, a skill that might just add to your employability.

Toward a theory of technical writing?¶

A question about whether documentarians suffer from imposter syndrome because we fail to appreciate our own subject matter expertise, and instead tend to defer to other SMEs, sparked a lengthy and thoughtful conversation about whether we lack a formal theory about the discipline.

It was generally agreed that a major consideration is technical writing’s focus on the practical, not the theoretical. Software documentation helps its audience get a job done. Its primary purpose is to inform and instruct and while these goals can be informed by theories from cognitive science and linguistics, they don’t need to be. Most documentarians don’t have formal training in the work they do. While code still publicly stands – or at least is perceived to stand – on the foundations of computer science and its theories, technical communication as an academic discipline tends to be further removed from real-world practices of documentarians.

Ranging further afield, folks pointed to documentation’s crucial work in defining audience, creating a single source of truth for the information products need to help their users, and establishing a role in designing and building the products themselves. Perhaps one contributor summarized it best when they said that technical writing “is a diverse field that pragmatically applies theories from other fields as they make sense in the situation.” In other words, we look to theory that’s informed by practice, rather than the other way around.

Toward the end of the wide-ranging conversation, folks dug into the question of documentation’s role in persuading users (in addition to informing and instructing). While some pointed out that this role is conventionally associated with marketing and that marketing language tends to get in the way of the primary goals of informing and instructing, the consensus was that good documentation can and does persuade users to either start with a product or continue with it. Documentation does all the things! … which might be part of why it’s so difficult to provide it with a useful theoretical foundation.

What we’re reading¶

The #bipoc group’s been discussing the following materials on diversity, inclusion, and equity. Want to join the conversation? Please join us in the #bipoc Slack channel!

A short read: Google, and other big tech companies, are struggling with caste discrimination after cancelling a Dalit History Month talk.

A medium read: Belonging to a community of support can help shape your career and your life. However, for Black people, it can be hard to find role models in the tech field. The New Stack writes about BlackTechTwitter and includes a list of accounts to follow.

A longer read: Textio released their Language Bias in Performance Feedback report. They found that when looking at job performance feedback, patterns of bias appear for most all underrepresented groups.