Home »

Write the Docs Newsletter – March 2020

Hello everyone! March is here (already?!), and so is a fresh new edition of the WTD newsletter.

Firstly, announcing some news I know some of you have been waiting for. We’re delighted that the results of last year’s salary survey are now live! Openness is a core value of this community, so it’s great to be able to present the anonymized data for your perusing.

On the conference side, it’s exciting to see the awesome roster of speakers for Portland - some seriously great talks to look forward to.

We do also want to address the situation with COVID-19. Currently, we have no plans to cancel the Portland conference, but are planning to take additional precautions during the on-site events. We’ll be watching the situation closely over the next few weeks, and taking advice from the Oregon health authorities and United States CDC as it comes. We will assess the situation again next week, and provide updates as the situation changes on our blog, using the tag covid-19.

Moving swiftly on - it’s been a month of great conversations on Slack, so let’s head on to our stories.

Job listings and managing your assumptions

How should you approach a job search when you’re more of the “writer who quickly learns technical topics” than the “developer who likes to write” sort of technical writer? February’s conversation on this subject included tips for targeting and expanding your search, as well a discusssion about avoiding the limits of your own assumptions.

In terms of tips, try searching for job listings that mention more traditional tech writer tools, like MadCap Flare. These jobs may involve more focus on writing and less focus on programming experience. You could also search for different job titles: tech-writing-adjacent roles like UI/UX writer, content designer or content strategist, technical editor, information designer, documentation specialist, and product writer or product education.

These tips bloomed into a longer conversation about how your own biases and assumptions can reduce the number of jobs you apply for. Here are a few key points to consider:

  • A more “technical” tech writing role may be open to someone who can write well already (arguably harder to teach) and pick up the technical concepts as they go. Make it clear that you’re willing to learn! Every new job has a learning curve, no matter how technical you are.
  • Write your cover letter and application to focus on the requirements that you do fit. You can address any gaps between your experience and the advert during the interview. If you’re worried that applying when you don’t meet all requirements is a waste of time, instead think of it as building experience talking about your skills and talents.
  • Treat job listings as a wish list, not a list of requirements that you must match exactly. A 2014 Harvard Business Review article described how this assumption affects women in particular, and tools like Shatter aim to help women apply to more jobs and present themselves for leadership roles. “Apply even if you don’t think you fit 100% of the requirements” is good advice for anyone. As one documentarian pointed out, if you qualify for 70% of the requirements, consider yourself a great candidate. Another put it this way: it’s not your job to turn yourself down!

No matter what, remember that the types of jobs open are always changing, so don’t get discouraged! There’s plenty of help available in our Slack community, especially in #career-advice and #job-posts-only; and don’t forget the Write the Docs job board.

Learning material recommendations

Folks across several channels have been discussing learning resources - ones for learning all sorts of skills useful to documentarians. There’s plenty of great stuff on a bunch of topics:

Fundamentals of tech writing

  • Join us for a two-chapter-a-week read-through of Mark Baker’s Every Page Is Page One in #learn-tech-writing!
  • There’s also Google’s Technical Writing for Developers courses - just released to the public last week.

Content strategy

API docs

Some folks use Postman to test and document REST APIs. Other resources include:

Git

Do we tell users what’s new in the docs?

This month, documentarians debated whether or not we should provide a “What’s New in the Docs” section - to detail changes to the documentation itself, rather than the product. It depends on how you do release notes for your product, and how much value docs release notes would add for your audience. If your team has the bandwidth, it’s worth considering - even if they’re just a section inside of your product release notes.

Arguments in favor:

  • When you create or update documentation outside of a release (for example, to address documentation debt or add a new tutorial for an existing feature set) release notes help make your readers aware there are improvements.
  • If release notes for the product aren’t especially descriptive (such as a list of Jira keys and summaries) including release notes for documentation changes can give users more context for the changes.
  • If your product’s release notes are targeted towards system administrators or similarly advanced users, docs notes may be more useful for end users.
  • Can demonstrate to your customers that you’re addressing their docs feedback.

Arguments against:

  • For many of us, our release notes cover changes to the product we’re documenting, and our documentation changes are in response to those changes. Release notes for documentation would simply duplicate the release notes for the product.
  • Who has the time?

Does your organization create release notes for the documentation? How has it been going? Come chat about it in Slack!

Some discussions on style

There’s often great discussion about particular points of style and style guides going on in #general. Here’s a summary of the high points:

Firstly on resources about and approaches to Global English. The Global English Style Guide from O’Reilly was recommended, plus there’s a relevant section of The Microsoft Writing Style Guide. And it’s not strictly about Global English, but there’s a decent section on global communications in The ASD Simplified Technical English dictionary. That was originally intended for a different industry (aviation), but still has helpful pointers.

Next up, how we feel about “e.g.”, “i.e.”, and other Latinisms. A beleaguered poster who uses e.g. and i.e. asked the community whether they were alone in their practice. Most replies advocated against these abbreviations: they’re often misused (for example, using ie to mean “for example”), and many feel their meaning isn’t clear to a general audience. The same argument goes for “etc.” too, and penty of the common software docs style guides agree. On the counter side, if you’re confident you can use them accurately and have grounds to believe your audience will understand them, it might still be fine.

And lastly: are tables, lists, or definition lists more readable? Lists are usually better if you’re optimizing for mobile; tables are better if you’re presenting complex matrices. And clearly it’s not a simple decision - what if you want to present a mobile-friendly complex matrix? Bear in mind also that it’s more challenging to copy/paste from a table. And for the author’s benefit, lists are often easier to work with if you’re using markdown or something similar.

Job posts

To apply for these jobs and more, visit the Write the Docs job board.

Community events coming up

COVID-19 Update 01   COVID-19 Update 02 - Postponing the Portland Conference