Home »

Write the Docs Newsletter – October 2021

Hello everyone!

It’s Beth here, writing while I’m listening in to Write the Docs Prague. I hope everyone who attended had a great time! For those of you who couldn’t make it, keep an eye out: we’ll be publishing the talk videos on YouTube fairly soon. And if you’d like to get more of a flavour of the conference, you can listen to the intermission music - which I am bopping along to as I type :D

And one more thing to keep your eyes peeled for - the Salary Survey is going through its finishing touches. We’re really excited to be continuing this work to improve transparency around documentarian salaries, so watch this space!

In the meantime, we’ve had another month of interesting conversations and insights from the Write the Docs Slack. Read on, and enjoy!

Docs review strategies for lone writers

Being a company’s only technical writer comes with advantages and disadvantages, but a common challenge for lone writers is getting reviews for documentation. When there’s no established docs review process and there are no other documentarians to turn to, here are some strategies the lone writers of Write the Docs use to get the work done.

You may be able to publish your best efforts without review and await (or seek) corrections, whether from users or others at your company. Docs have bugs just like code, and speedy fixes may be more within your control. The downside with this approach is any mistakes are public until you fix them.

The fastest way to get corrections may be to publish errors, but sometimes that’s not an option. In this case, try to assemble an informal group of docs review resources. Seek a product manager or subject matter expert to review docs for accuracy. For readability, look for someone else whose job requires writing, perhaps in marketing or communications. Your experiments here could help drive support for a more formal docs review process.

Some lone writers solicit docs review by creating feedback channels in Slack with the Workflow Builder. For example, you could create a #documentation channel with a built-in form for submitting correction requests, with fields for specifying the page in question and the requested corrections. Then the Slackbot can notify you when someone submits a correction.

For detailed instructions for setting up your own docs feedback workflow in Slack and other insights from this discussion, read Darryl J. White’s blog post Editing and Gathering Feedback.

Equipment you find useful for working remotely

What are the most useful tools for working from home? This question sparked a lot of conversations this month, but top of everyone’s list was multiple monitors. The simple ability to see more than one thing at a time is hugely helpful, and the benefits of improved productivity and less window-switching have made them essential for work-from-home life.

Other recommended tools mentioned were sit-stand desks and computer accessories like comfortable wire-free mice and keyboards. Aside from hardware tools, software applications like Grammarly, macOS’s Voice Memos, and BetterSnapTool proved beneficial for working from home. Even traditional tools, like a whiteboard and pen and paper, were brought up.

With so many software and hardware tools available, it can be challenging to pick the ones that are worth putting in the metaphorical “toolbelt.” However, whether you want to be more organized or keep track of important meetings, there is always the right tool for the remote job.

What’s in a documentarian resume anyway?

As anyone who spends much time around the Write the Docs community knows, the questions around just who writes the docs, what their job titles might be, what their skills and experience might be, have no single definitive answer. One of our longest recent threads about job descriptions and resumes explored a number of possible answers, though. Here’s what we took away from the 100+ message thread:

  • Writers and hiring managers alike struggle with whether to focus on docs-specific skills – writing, tools, workflows – or on specific technologies in search of docs. Folks seemed to agree, though, that a documentation position that requires familiarity with the specific tech to be documented needs to emphasize required skills. And finding just the right fit is a challenge whether you’re hiring or looking to get hired.
  • Writers with non-writing backgrounds can prefer not to list specific tech on their resumes, especially coding, for fear they’ll be considered overqualified or otherwise not the right fit. Other writers are reluctant to mention specific tech if they’re not experts, for fear their skills will be challenged, or assumed to be greater than the writer feels they are.
  • Some writers emphasize their ability to learn new tech – they consider themselves generalists with strong research skills and experience picking up new areas sufficiently to be able to document them well. Others emphasize their skills in specific technical areas – they consider themselves specialists with the ability to take on non-writer work as needed, especially in QA, design, UX, or support. Curiosity and eagerness to explore and learn were attributes everyone seemed to agree are vital, whichever approach you choose.
  • Job seekers: be thoughtful about what you put on your resume, don’t rely on LinkedIn alone, and try to tailor your job searches to companies you think might be a good fit for what you want to do – whether it’s tech you want to learn, tech you know a little about, or tech you know a lot about. Cover letters can help you show how you fit a job listing, beyond what you put in your resume.

If you’re interested in pursuing the conversation, join us over at the GitHub Discussion one stalwart WTDer started. Carry on, folks!

What we’re reading and listening to

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!

In the United States it’s Hispanic Heritage month.

A short read: From Courageous Conversation, do you know the difference between Hispanic and Latino?

A longer listen: From MPR news, How the term Latinx, and other labels, miss the mark. This episode talks about labels such as Latinx, BIPOC, etc, and explores where they started, what they mean, and who uses them.

Virtual events coming up

Get Ready for the Conference!   Conference highlights and thanks to the community!