Home »

Write the Docs Newsletter – July 2021¶

Good morning, afternoon, or evening, documentarians! It’s Beth and the newsletter team with a last summer update before we head off on a little break. We’ll be back in September :)

The main announcement for the month is that the CFP and ticket sales have opened for the Australia and India conference! As with our other conferences this year, it’ll be held online, and the dates for that are 2nd-3rd December. The CFP is open until 15th August, so get thinking about talks you’d like to submit!

Onto our stories from Slack…

What’s best for your images - JPG or PNG?¶

JPG or PNG? Which is the best format to use? Does it even matter which you pick? Well, the Write the Docs community has chimed in to answer your pressing questions, and it seems like PNG is the clear winner. Portable Network Graphics, or PNG, offers unmatched clarity for screenshots in online docs and doesn’t degrade when opened and saved like the alternative JPG or JPEG. Compression in PNG is also better since it’s a lossless image format and not a lossy one like JPG, meaning it preserves all of an image’s details. Another advantage of PNG is that it supports transparency, whereas JPG is best for gradient images.

Curious to know if there’s something better than PNG? There is, and it’s called WebP, a format that works for both lossy and lossless compression. If you have a tool that exports to WebP, use it instead of PNG or JPG for enhanced web images. Otherwise, stick with PNG for clear, detailed, high-contrast images.

For more help choosing the right format, check out this article by Allison Boatman or this one by Shane Melaugh.

Designing a tech writer career ladder¶

What does a technical writing career ladder look like? This month while discussing how to set one up, we saw a few examples - GitLab’s technical writer ladder, and career-ladders.dev/docs. Some community members saw value in aligning title levels across functions. So a standard progression applied to tech writing could look something like this:

Associate Technical Writer / Technical Writer I
Technical Writer / Technical Writer II
Senior Technical Writer / Team Lead
Staff Technical Writer / Manager
Principal Technical Writer / Director
Distinguished Technical Writer (?!)

Many felt including “Distinguished” was a bit unusual. It’s nice to have it there to have something to shoot for - to show what a tech writing role can look like at that level. But it’s okay for a company just not to be able to support someone at that level, when Distinguished usually means people who have an ecosystem-wide or industry-wide impact.

Even the other high levels can be challenging to reach, especially as an individual contributor. Many companies need managers much more than high-level ICs, or simply don’t have scope to do work at such a high level. But there was general agreement on the importance of having clear standards for what each level means. It can be really frustrating if someone wants to get promoted but the ground keeps shifting.

How long should it take to reach the “senior” level? Surprise surprise, there’s no clear answer. We see 5 years mentioned a lot in job adverts, but some folks said it took as little as 2 with the right domain knowledge. Of course, seniority shouldn’t purely about the number of years you’ve been in the role - most felt it was more to do with your skill level, and the breadth and level of responsibility you take on. Take these titles with a pinch of salt, though, because what they mean can vary wildly between different companies. For on what it means to be senior, see Distinguishing between junior vs senior tech writers from the June 2018 newsletter.

Doc history and Git¶

When you’re creating a new version of docs for a release, how important is it to keep the docs for old releases? The simple answer is to keep all history, just in case - you never know when you’ll need it. But some docs are so outdated that the original writeup is incredibly unlikely to be relevant.

How to keep the history depends on how you want to use it. If you’re using Git and you just want to be able to check the history, you can see it with git log. Though it can take some archaeological work to follow the trail when files get moved.

But what if you want to publish those old docs? One option is to copy your old files alongside your new ones. It’s possible to copy the files while retaining their history, but it takes some effort. However, be aware that Git doesn’t track files exactly. It tracks some content (blobs—sequences of bytes), and trees of file names that point to blobs, but it doesn’t actually track those things together, which is why that blog post has to use merges to copy the history. It’s fighting the way Git wants to work. It might be simpler to copy the file with a commit message saying where it was copied from, to help someone track down the history if they need to.

If you can publish from something other than HEAD, you can do something much simpler: just use Git’s tagging system to mark the commit for an old release, and then publish from that tag. Some teams use different branches for different releases, which would make this even more straightforward.

What we’re reading and learning¶

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: This article on Axios talks about LinkedIn starting to pay ERG leaders, usually a volunteer position, for their work.

A medium read: this Great Place To Work article highlights strategies to improve inclusion and equity in the workplace.

For a much more in-depth exploration (several weeks), Coursera now has two free courses on Anti-Racism offered by the University of Colorado, Boulder: course one and course two.