Home »

Write the Docs Newsletter – August 2020

Dear documentarians of the world - good morning, afternoon, or evening! It’s Beth here, writing to you on an absolutely sweltering day in Switzerland. 36°C has been rather a challenge in the home office; on the plus side, being at home means a mid-afternoon siesta is now an option…

The online Portland conference is fast approaching, on 9-11 August. Tickets are on the verge of selling out, so if you’ve been sitting on the fence about whether to go - get a move on! Here’s the schedule if it’ll help you make up your mind.

And if Portland isn’t in a convenient time zone for you, fear not! because the Australia and India online conference has just announced both dates (3-4 December 2020) and a call for proposals. We cannot wait to hear from documentarians far and wide - get those talk proposals submitted by 31st August.

Next month, the newsletter team is on our summer break - so enjoy this month’s articles, and I’ll look forward to popping back into your inbox again come October. Stay well!

To git or not to git docs as code

Everybody’s asking about a docs-as-code workflow and toolchain these days - one recent question about adopting it for a team that’s unfamiliar with Git sparked a useful discussion about this potentially rather painful learning curve. Here’s the advice from folks who’ve brought teams up to speed with Git:

  • It’s crucial to have at least one Git expert available to help troubleshoot. Both because as people are learning for the first time, and because everyone on the team (no matter how proficient) will encounter new and unexpected issues.
  • Make time for proper training. Find someone in-house, bring someone in from outside, give people time to take online courses. Two recommended resources were a YouTube video, Git and GitHub for Poets, and a Udemy course, Git and GitHub for Writers.
  • Consider GUI clients instead of the command line. Folks mentioned GitHub Desktop, TortoiseGit (Windows), Tower, Sourcetree, and GitKraken.
  • A lot of learning Git is about building confidence with an unfamiliar workflow and new underlying concepts. Once people get through the initial learning curve, stress levels tend to settle down.

A tale of two careers

Want to be a technical writer and work in a different field at the same time? Is it possible to juggle two careers without burning out? The reality is that technical writing requires a lot of time and effort; it’s not easy to balance this with other work, but it’s possible.

Acknowledge and prepare for the difficulties. Accept that this balancing act is hard, and that’s okay. There are only so many hours in the day. If you can’t give 100% to both, there’s a good chance this isn’t the right path. It’s more realistic to turn one of your jobs into a side project. Having two careers implies serious intent to progress in both things simultaneously. This will take a lot of energy, devotion, and time spent working.

If you’re determined to maintain the balancing act, occasionally switching between both jobs will give you a nice change of pace. In some cases, one job may inform the other or even provide you with a fresher perspective. Also, consider how you could merge responsibilities to create a hybrid role. They may be more compatible than you think.

Reflect on how to create a long-term option that fulfills most of your desires. So long as you have the physical and mental time for the two, you’ll be happy with technical writing and the other career that balances it out.

What to do with tricky little details

In an ideal world, structuring documentation pages is easy. You cover the main concepts and the core tasks with clear, user-centered headings, and you’re done.

But in messy reality, it can be tricky to fit all the relevant information into those headings. Where do you put non-standard uses, or fringe cases? Granular but important details that users won’t find anywhere else? Questions that often come up in support?

One option is to have a Frequently Asked Questions section at the bottom of the page. Readers are often familiar with FAQs as a format, and may even specifically request them. But FAQ can be a misnomer - for fringe cases, the questions are by definition not frequent. Besides, some folks feel that FAQs are a poor content design pattern.

You could use a more general heading like Questions, Q&A, or Notes. However, these give you very little hint about what you’ll get out of reading these sections - you don’t give readers much of a reason to scroll down there. If you can be more specific about the type of content, that might help: headings like Troubleshooting, Limitations, Gotchas or Tips.

Alternatively, embed the information into the main sections. It’s a tricky balance: too many side notes, and you muddy the page for your core audience. But sometimes these asides are worthwhile - particularly if they’re not essential info, but help your reader understand the topic better.

Finally, if you’ve got a knowledgebase designed for micro-articles, you could split each factoid out into its own page, and link to them from the main article. The bigger the tidbit, the more this makes sense!

Job posts

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

(Remote) community events coming up

Tickets Selling Out Soon and Welcome Wagon Guide   Announcing speakers