Home »

Write the Docs Newsletter – October 2019¶

Hi, everyone, and welcome back to the newsletter after our summer break!

Top news this month is our salary survey. It can be tough to work out what “normal” pay is, so Write the Docs is carrying out a salary survey to try to get some answers. The survey is open until 31st October, and we’ll be publishing the anonymized data for free. Help the community and fill it out here!

On the events side, I thoroughly enjoyed meeting so many of you at the Prague conference! If you missed it, don’t despair, because all the talks are now up on YouTube for your enjoyment. Plus there’s one last conference to look forward to this year: we’ve announced the speakers and schedule for Write the Docs Australia, coming up on 14-15 November.

So that’s all the news! On to the latest and greatest stories gathered from Slack.

Behind the scenes with fonts, emojis, and Unicode¶

This month, a question about icons and fonts provided a goldmine of information about emojis and unicode. Here are a few interesting facts:

The “key” underneath all fonts is Unicode. Fonts just provide glyphs for the underlying Unicode values - and different fonts can have different glyphs for the same Unicode.
Fonts and typefaces are not the same! A typeface includes more than one font, as fonts are variations on the base (the typeface).
In theory, two typefaces could have very different glyphs for the same Unicode code point, but it’s more standardized these days.
On a Mac, to get the correct glyph for a font, search in the Character Viewer for the Unicode code. You can also mark your favorite emojis in Character Viewer to help you find them quickly.
Many apps have an emoji menu (look under “Edit”) that opens Character Viewer.
Standard emojis have their own Unicode code points - check out the full Emoji list.

Quite a few helpful links were also dropped into the discussion, including:

Feeling like a fraud and how to deal with it¶

It’s totally normal to sometimes feel overwhelmed and to doubt your abilities - especially if you’re writing about unfamiliar products. But there are lots of ways to get back on track. Here are some the community suggested:

Insert a hypothetical user into the conversation. That way you function as a user advocate, re-engineering the docs to meet users’ needs and wants. For example, asking “If a user tried to follow these instructions as they are, what info would they be missing?”
Talk to product managers, subject matter experts, and customer support. These roles may have more information about the users’ requirements.
Establish some clear, short-term deliverables for your work, to get some early wins and regain confidence.
Remember that you took time to learn the things you already know, so don’t feel discouraged when you feel like you can’t grasp new material instantly. This work is difficult! Step-by-step, you’ll eventually understand the product and get the knowledge you need.
Make a list of skills and knowledge that you feel you’re missing, and then work out what you’d need to do to fill the gaps. Or, make a list of specific, concrete things you want to achieve, have achieved, expect to achieve. Involve your manager so you can turn them into actionable goals. Success is a work in progress.

If you’re interested in setting clear actionable objectives to improve your performance, check out the SMART criteria.

Leading and following: finding a mentor, being a mentor¶

Another great way to build both your confidence and your abilities is to find a mentor, as we discussed recently in #career-advice. General agreement that having a mentor is A Very Good Idea led to some handy info:

In the UK, the ISTC has a lightweight mentoring program. One program participant explained that there aren’t many guidelines, so they set up a development plan with their mentee and gave feedback on the mentee’s CV.
It can help to draft a development plan to show to a potential mentor, so they know what you’re looking for. For ideas, see the ISTC’s Example CPD Records.
Some companies provide formal mentoring programs: people who want to mentor sign up and describe their expertise, and you contact them if you want to be mentored. These programs typically provide internal resources for mentors and mentees as well.
A useful article: How to Email a Potential Mentor the Right Way.

A couple of contributors suggested that WTD start its own mentoring program, which sounds like an idea we’d love someone to take on! If you’re interested, #meta is a good place for that conversation. And if this topic captures your interest, see Arran Southall’s talk from Prague this year, Fostering Talent: Mentorship, Peer Reviews and Going Beyond Your Job Description.

(Side note: One could argue that we shouldn’t use the term “mentee”. Classically speaking, the right word for someone being guided by a Mentor is, of course, a “Telemachus”.)

Deciding on a new tool…¶

If you’re struggling with the limitations of your docs tools, how do you decide what system to migrate to? In a recent conversation about trying to replace an old CMS, documentarians on Slack compared MadCap Flare, Paligo, static site generators and Adobe Suite, among others.

There was some consensus around establishing your specific business requirements before selecting a tool. What outputs do you need to publish? How much do you need to reuse content? Does OS compatibility matter? How long will migration take? The requirements matter because no single tool is right for all situations. If you understand your needs well, it’ll really help - you might even realise that you don’t need to switch.

Separating features into must-haves and nice-to-haves makes evaluating tools easier. Take care not to get side-tracked by features that don’t address an actual need you have! Someone posted a useful list of features to use as a starting point for your own evaluation.

There are many tools out there, and no one size fits all; make sure you know what you need before picking one.

… and migrating to a new tool¶

Migrating docs from one tool to another is hard, and the bigger the doc set, the harder it is. On top of the technical challenges, there can be content problems too: what do you do if the docs are in dire need of revision?

The community agreed that it’s not wise to try to improve docs as the same time as moving. Migrations are hard enough as it is! Better to resist the urge to edit as you go, and improve things in a second phase after the move.
Alternatively, weed your docs beforehand. Carry out a content audit to make sure what you’re moving is worth the time and trouble. Some bad content you can abandon and start over.

Some useful rubrics: ROT (Redundant, Outdated, Trivial); OUCH (Outdated, Unneeded, Current, Have to write); MUSTY (Misleading, Ugly, Superseded, Trivial, Your collection has no need of this - discard it!).
Everyone agreed they’d underestimated how long a migration would take. Consider migrating in stages, starting with pilot docs that you’re confident will work well in the new tool. This lets you learn about problems nice and early. Ideally the pilot docs should have updates on the horizon but not imminent - it’ll take longer to move than you think.
Be wary if you’re expected to keep up your normal work at the same time. Lots of people recommended having headcount dedicated to the task. It’s often a good subject for contractors or interns, because the projects don’t require that much context.

If you’re looking for somewhere to chat about these decisions, head over to #doc-tools!