Home »

Write the Docs Newsletter – April 2019

Hello folks! Beth and the newsletter team here, welcoming you to the April edition of the newsletter.

Spring is here and that means conference time is speeding towards us! Portland (19-21 May) is very nearly sold out, and I’m excited for those of you who’ve got tickets, because the lineup looks fab. There’s tons of things to tell you about the conference and I’m not even going to try to cover them all - check out the blog post for details on childcare, diversity tickets, shirts, and much more.

In Europe, ticket sales and CFPs are open for both Prague and the brand new Vilnius conference. The Vilnius CFP closes 22 April, and the Prague CFP closes 30 April. We can’t wait to hear your ideas!

So that’s the news this month. Read on for stories from Slack, plenty of job listings, and tons of meetups around the globe!

Page length and user preference

This month, the WTD community discussed whether users prefer shorter or longer pages in documentation. Both options have upsides and downsides, but most documentarians seemed to feel that longer pages work better for users, and some reported their user feedback has been strongly in favor of longer pages. Here are some of the issues folks discussed:

  • It’s important to keep navigability at the front of your mind when you’re writing longer pages. Site search, floating menus with links to sub-topics, and clear sub-headings all help make content more discoverable and skimmable. Plus, if all else fails, users can search for key terms using Cmd/Ctrl+F.
  • With shorter pages, users may have to click around through more topics to find the information they need. It’s also more time-consuming for users to use Cmd/Ctrl+F repeatedly on shorter pages.
  • On longer pages, it’s easier for users to miss or skip over information they need to know before they get to what they want to know. One person is experimenting with adding validation checks in procedures to help minimize this problem. Most agreed that “we tried to warn you…” is not an ideal solution!
  • Because so many topics are listed on a single page, longer pages can make it more difficult to figure out which topics users are reading the most.

If you want to dig in further, some people also recommended the I’d Rather Be Writing posts Making Help Content Enjoyable to Read - Impossible Quest? and Subheadings: Perhaps the Most Useful Technique in Technical Writing.

Google’s Season of Docs

We’re excited to share with you a new event from Google: Season of Docs!

Season of Docs is a three-month program for new and early-career technical writers looking to get involved with open-source projects. Open-source organizations can submit project ideas based on their current documentation needs, and Season of Docs will match them with an aspiring documentarian. Experienced technical writers can mentor those new writers, helping them to learn any new tools, understand requirements, and polish up their documentation. Participating technical writers earn a stipend.

You can learn more on the Season of Docs site, as well as on Sarah Maddox’s blog post, Season of Docs fostering open source collaboration with tech writers.

Important dates

A complete program timeline is available here.

What’s in a code comment? And other musings on developer docs

One contributor’s sharing of a discussion elsewhere on the web about the fallacy of “self-documenting code” produced a lively extension of the conversation into what makes not only good code comments, but good docs more generally. Some highlights:

  • No, Virginia, you cannot get all the information you need from inspecting the code only.
  • But there is such a thing as too much information. You don’t need to restate the obvious, in code comments or in documenting a GUI.
  • The really difficult task, in documenting code as in any other software interface, is determining what the user needs to know to succeed in their tasks.
  • We always need to think about different user personas, different needs, and how best to address them all without either hiding information or letting a crucial detail get lost in describing all the other details.

Dealing with competing priorities

In a discussion on #lone-writer, someone asked: What do you do when lots of people are asking for your time? Particularly when everyone wants to be the highest priority, and you really want to help them all out. It can mean you end up always reacting to the latest emergency, with no time to take a breath and work strategically. How do you avoid burning out like that?

Lots of commenters talked about helping those asking you to understand the situation: the different demands on your time, the work you’re doing, and the constraints. One way is to make the work visible: for example, having a board so you can show people what’s in flight. It can help them understand your priorities: for example if you’re fully booked this week because of another team’s work.

It’s worth checking if the person requesting can help by gathering the information needed. If they agree to do the groundwork, it takes some of the burden of emergency work off you.

Be aware that you likely won’t find time to think strategically: you have to make it. One suggestion was to block off time in your calendar for this, even if you can only start small. For an idea of what to do, see Neal Kaplan’s talk on triaging.

And keep taking care of yourself - knowledge work requires a functioning brain! If you’re fried, don’t be afraid to take the breaks you need.

Community events coming up

Call for Volunteers and CFP Reminder   Announcing Full Schedule, Live Streaming, and Tickets Sold Out