Home »

Write the Docs Newsletter – July 2019¶

Hi, WTD friends, and welcome to the July newsletter! It’s Beth A here writing from sweltering Europe, where I’ve been learning great new words like canicule and Hitzewelle - aka heatwave in French and German.

(Fun fact: canicule comes from the Latin dies caniculares, or “dog days” - the most uncomfortable part of summer, so named because they come after the heliacal rising of Sirius, the Dog Star. Well, I thought it was interesting.)

Aside from fascinating facts about the weather, we also have some exciting announcements for you. Firstly, tickets are on sale for the Australia conference, and the call for proposals is also open! The CFP closes on 9 August, and the conference itself is 14-15 November in Sydney.

As for Europe, you’ll be pleased to know that Prague speakers have been announced! Here’s the full list, and you can grab your tickets here. Plus, if you’re interested in helping out behind the scenes, we’d love you to volunteer at the conference.

Lastly is a cool addition to the Hiring Guide. The Career Community Spotlight is a series of interviews about how people became documentarians, including tips for how to follow the same path. Please share with anyone interested in getting into the industry, and if you’d like to share your own story, get in touch!

So that’s the news. What have we been talking about on Slack this month?

Making the leap to managing writers¶

One of our big discussions this month was about folks weighing up opportunities to move into managing writers. Here’s the guidance the community gave.

There are definitely some things to be wary of. If writing’s your passion, moving to management means less time for it. This can mean losing touch with the craft, and leaving your portfolio lighter if you decide to back out. Another issue is that you’re accountable for both the successes and failures of your team, which can be stressful.

But the upsides of management are the bigger projects that can challenge you in different ways, including helping your team reach their full potential. In the long run, teaching others lets you achieve more than you would have been able to on your own.

If you’ll be hiring, recruitment can create a more direct sense of accomplishment. On the flip side, you may also at some point be responsible for letting people go, a daunting task.

The general conclusion was: it’s not easy to make the move, but if you’re happy to spend less time writing and to contribute in a bigger way instead, it might be for you.

For those considering management, take a look at Rands Leadership Slack, which offers coaching and educational resources. It’s also worth checking out the episodes of Tom Johnson’s podcasts on how to manage an all-star team of technical writers: Managing Writers and Managing Virtual Teams.

For those who might consider freelancing…¶

… a generous Slack contributor provided a wealth of information and advice about what to look for and what to expect in the land of freelance work.

We were planning to write this up for the newsletter, but very kindly the contributor did it for us! So you can read all about it here: Real Talk: Freelance/Contract Writing

A few other people also weighed in with some comments. Some don’t work with a 1099 but set up their own corporations (S-Corp or LLC), and then work as their own employees. This approach can provide tax benefits for US workers, and can sometimes make you more appealing to a larger employer. People also suggested that professional support, in the form of a lawyer or accountant, is important if you’re planning to work freelance long-term.

And if you’re going the independent route, don’t forget to consider staffing agencies. They get a cut of whatever the client pays, but they sometimes provide benefits and ease the paperwork burden.

What to do about text wrapping¶

A very specific topic, but one that usually comes when working with docs-as-code: should you mandate text wrapping in your docs source, and if so, how? For some background before digging into this summary, check out To Wrap or Not to Wrap: One of Life’s Greatest Questions.

Forcing a hard wrap at a particular character count or column helps avoid reflow problems, but causes other problems. For example, hard wraps:

create awkward line breaks on devices with different screen sizes
wreak havoc on diffs
make text more difficult to parse for people who are translating to different languages and people with cognitive disabilities

Hard wraps also interfere with using filters like grep to search for words and phrases within a file. Soft wrap is an option for preserving searchability, but it requires everyone to use a text editor with soft wrap support.

Several people mentioned one sentence per line as a solution, noting that it’s the recommended approach for AsciiDoc.