Home »

Write the Docs Newsletter – February 2022¶

Hey everyone! Your newsletter team is back in business for a brand new year, and we hope 2022 has been treating you alright so far.

Just to let you know about a recent announcement: we’ve decided that the Portland conference will be virtual after all. It’s been just too difficult to make hybrid work as we wanted - full details in the blog post.

But we’re looking forward to running another great virtual conference, and tickets are now available. The Call for Proposals is open until 25th February - and if you’ve got an idea but haven’t quite formed it into a proposal, consider attending the East Coast Quorum meetup’s Proposal Workshop for a helping hand!

On to our stories from the month!

Résumé formats - the tradeoffs¶

This month, our documentarians shared their experiences with a less frequently discussed dimension of résumé prep: format. Applicants who use Microsoft Word to prepare their résumés, for example, and then submit them in .docx format might not realize that there are perils downstream. Reviewers may not have access to Microsoft Word to open the file; or they might open it with a tool that doesn’t deal with the formatting perfectly, like Google Docs or Pages for macOS. Even when reviewers do use Word - different software versions, unavailable fonts, or customized style settings can change how the résumé looks, and .docx files can be corrupted as they fly from one inbox to the next. If this happens, the job seeker may never reach a further stage of candidacy.

Even stickier, applicants have no way to know what tools the reviewers have! Job descriptions don’t always specify a résumé format, so it’s safer to go with a more universal option. PDFs solve many problems: your résumé will look the same for everyone, no matter the PDF viewing tool. PDFs also make it difficult for recruiters to change your résumé after you provide it. But some mentioned uncertainty about whether applicant tracking systems can properly read PDFs, a problem if the company is looking for particular résumé keywords. Still, most people reported no problems with submitting or reviewing PDF résumés, so it seems to be a safer bet when the job ad is silent as to preferred format. For alternatives, there’s always the more-accessible plain text or HTML - or hosting your résumé on a personal website.

In the end, format is just one more choice to make when deciding how to present yourself to prospective employers. For an interesting take on how the pandemic has changed—or not changed—résumés, one writer suggested The Pandemic Changed Everything About Work, Except the Humble Résumé from The New York Times.

What about the “tech” in “technical writing”?¶

What technologies might a technical writer need to know? A recent discussion on this topic produced wide-ranging responses; and along the way, the conversation provided a glimpse into the range of industries and expectations our community works with.

Write the Docs began as a community focused on developer documentation, with an emphasis on tools and workflows programmers are familiar with. But we’ve grown in breadth and depth since those days, and our notions of technologies we need to do our jobs have grown, too. Ideas about technologies important for documentarians fell into two main categories, with some replies emphasizing tools of the trade, and others focusing on domain knowledge – the technologies you might be writing about.

Overall, the consensus seemed to be “domain knowledge trumps all.” When you’re interviewing, show what you know about what the company builds – the jargon and product and markets for security, for big data and machine learning, for devops tooling, or whatever it is that you’d be writing the docs for. Docs tools might matter to some interviewers, but they all will care about your familiarity with the company’s product and market.

As for docs tools, this has two sides: GUI-based vs tools in the docs-as-code category. For the first, helpful tools might be: MadCap Flare, Framemaker with and without XML schemas, SnagIt for screen captures. And a fair number of folks recommended tools for docs-as-code: Git, Markdown, static site generators, CI/CD pipelines, command-line tools, and possibly a scripting language. JavaScript was mentioned most often, but Python came in with quite a few votes too.

It’s related to which code languages a technical writer might find most useful. Beyond JavaScript, Python, and markup languages, there are plenty of other possibilities. JSON/YAML for data, XML for data and for content management, HTML/CSS because web development can be part of a tech writer’s responsibilities, and SQL because there’s nothing like it for learning how databases work.

“Just enough” was the watchphrase though – as with tools more generally, the most important thing is what you need to know and understand to get the work done.

Taking steps into leadership¶

Transitioning into a leadership role might seem like a Catch-22: how do you show you can lead without being in the role already? However, there are several practical ways to advance in your career.

First, there are ways to demonstrate your leadership abilities even if you aren’t in a leadership role, on your résumé and in applications. For example, did you mentor or help new colleagues onboard? Did you drive an effort to improve a process? If so, you can highlight this experience and the skills involved. Even include how you performed on your reviews, especially if it mentions leadership qualities.

Within your role, you can be clear about your professional goals - sometimes your manager can find you opportunities to gain experience. Another suggestion is to move laterally into a different role with more exposure. Lastly, don’t forget the option of more formal learning to develop or improve skills. Coursera, LinkedIn Learning, and Udemy all offer great leadership courses.

Of course, when you assume leadership and management responsibilities, you must understand that the nature of your job will change. For example, you may write less as a writing team manager since administrative tasks take precedence. Instead of leading a writing staff, you may want a senior-level position where your work is the same but with more non-managerial obligations. There’s a lot to consider before and during the transition; however, these suggestions should be a solid starting point.

What we’re reading and watching¶

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: What’s in a name? Psychology Today has an article on the effect of mispronouncing names.

A list: In the United States, February is Black History Month. Parade offers a list of books recommended by Black booksellers.

Explore: Check out the Searchable Museum to learn more about American history through the lens of the African American experience.