Home »

Write the Docs Newsletter – July 2020¶

Hello, everyone! It’s Beth here, with the latest edition of the Write the Docs newsletter. As I write to you from here in Switzerland, summer seems to have finally arrived. Here’s to bright sun and blue skies ahead, and hopefully a bit of a break as the summer holidays come along.

Big news this month is that the call for proposals for the virtual Prague conference is open! The deadline for proposal submissions is 22nd July.

The exciting thing about a virtual conference is that, without the limitation of travel, it’s an opportunity for us to hear from folks who might not usually be able to attend. So I strongly encourage you to submit for the CFP, and to tell your friends and colleagues about it - particularly if you or they are from an underrepresented group, or from outside Europe and the US. Bring us your big ideas, your handy hints, your revolutions and evolutions, your new takes on old ideas, your insights and your experiences. We would love to hear what you have to say.

With that - what’s the WTD community been talking about on Slack?

A magnificent array of management topics¶

This month treated us to several broad and deep discussions related to management. First up, interest in managing vs. writing: what should you do if you’re not sure whether a tech writer on your team is interested in management duties?

Just ask! It’s important to know up front if the answer is “definitely,” “not at all,” or something in between, so you can figure out if their level of interest matches your expectations.
If they do seem interested, be clear about the expected duties, and what control they’d have. Would they control hiring and performance reviews? Or would it be more around mentoring and training?
Consider options for testing the waters without committing to full-time management. Team or project lead can be a great starting point.
If they aren’t interested, don’t force it. If someone is happier as a hands-on contributor, they may be miserable in management.

What if you’re on the other side, considering a move into management - how do you decide?

Pros: you can achieve bigger projects as a manager than by yourself; you can help other technical writers grow, which can be extremely rewarding; if you enjoy facilitating and attending meetings, you’ll be in your element.
Cons: many writers just want to write, and there can be less time for that; at some point, you may have to shoulder the burden of firing; plus these 17 Reasons Not to Be a Manager.
Check if you’re doing management work already without realising it. Perhaps you take a special joy in managing and planning projects, including making sure your teammates feel good about projects and their work. Or, maybe you’re helping with team morale, eliminating barriers to people getting work done, or supporting your peers’ career growth.
Taking on management responsibilities without being a lead/senior can change how you’re perceived, so it’s worth being thoughtful about it. This piece by Tanja Reilly describes how such so-called “glue work” can affect your career.

Gathering documentation feedback¶

To improve documentation, we need to know where it’s lacking. We can get this feedback from a variety of sources, including user interviews and internal surveys. Here’s some advice from our community on how to go about it!

Your readers usually aren’t thinking about the docs but about their tasks. So, make it simple for them to share their thoughts. Initial quick responses are usually the most honest feedback you’ll gather.
Try a short meeting with docs readers to learn about their pain points. Ask them to walk you through a daily task, or follow a doc to achieve a task. Pay attention to the nouns and verbs they use - it can help you match the terms that your users think in.
Ask them to describe occasions when they had a problem and referred to the docs and/or contacted support. With specific examples of things that helped the person (or wasted their time!), you can plan to do more of the former and less of the latter.
In review requests, guide your responder towards the area of feedback you need, by asking specific rather than open-ended questions.
Keep surveys short and easy. People likely won’t complete if it’s too much effort, perhaps unless you’re paying them for their time. You can make it easier with “click yes or no” for statements like:
- The docs have the right amount of information.
- I easily found the exact information I was looking for.
- The examples are accurate and easy to follow.
If most questions are click-to-answer, a limited number text entry fields (e.g., to answer “What else would you like to share about your experience with the docs?”) can limit the effort.

The engineer and the writer can be friends: tales of collaboration¶

A question about how to write sample apps and tutorials spawned a wide range of sub-topics! What workflows are optimal? How do engineers and writers build good working relationships? What skills do developer-doc writers need? What part does company culture play?

Many people seemed to think the optimal workflow includes both writers and engineers collaborating to produce prose and code together. Ideally, you include cross-training in such collaboration, so that engineers improve their usability and writing skills and writers improve their coding skills.

However, in some company cultures it can be difficult to get engineering resources to help with samples and tutorials. In spite of the critical importance of good documentation, especially for APIs and developer tools, many companies (especially at the startup stage) see documentation as a nice-to-have. As they grow, they often realize they need to change priorities, but it can be a difficult shift to make. But it’s worth making a sustained argument for the value of engineering contributions to better docs. One thing that can help is that developer users increasingly expect good docs, and make their expectations known on social media.

Some writers do write sample code alone, with only occasional help from engineers or product managers. This depends on having the skills: a fair number of participants made the point that writers who can code are hard to find because coding full-time typically pays much better tech writing jobs. But a few folks seemed to think this situation is changing, at least at the more senior tech writer levels. People also seemed to agree that career advancement possibilities are much better for engineering roles, to the point where several announced their plans to move from docs roles to engineering roles. A couple of people recommended taking on the role of scrum master, which can help a writer’s perceived value to engineering.

Tracking work¶

Tracking documentation work can be challenging, especially if you’re handling docs tasks across multiple audiences, dev teams, or products. But tracking gives you a way to show your stakeholders where your time is going, where you’re making a difference, and how much progress you’re making. Here are some ways that WTD folks have tried to solve this problem:

GitHub’s task tracking features: These can let you use the same tools as development teams for showing progress, but a coherent system for showing tasks is time-intensive to set up.
ZenHub (GitHub app): This tool introduces a drag-and-drop Kanban board to your GitHub project, to make it easier to visualise task progress.
Trello: Trello is very customizable, as you can create cards, labels, and boards to track tasks as you like and display them to a variety of stakeholders. Some documentarians used a different board for each product they work on, or labels and card assignments to track issues across the docs lifecycle.
Jira: You can include a documentation component within your project. This allows people in your organization can log issues against the docs, and you can use Jira’s features to track your issues by filtering on that documentation component.
Meetings: The old-fashioned way! You can hold regular meetings with your stakeholders to give them status updates on how your work that concerns them is progressing. It’s also an opportunity to get details on what’s coming up on their roadmap, and to hear about key priority changes so they don’t surprise you at the last minute.

If you have found a great way to track your docs work, or you’d like to ask for more tips, jump into the Slack!

Resources for diverse example names¶

One of the most straightforward ways we can make our docs more inclusive is to make sure that example names in our docs reflect a wide range of people. Here are a few resources the community shared for choosing more diverse example names:

Wikipedia’s lists of most common forenames and most common surnames by region.
Diversity Style Guide
Splunk style guide on example names
Behind the Name - name generator

We’d love to hear about more ways that you’re prioritising inclusivity in your docs work. If you have something to share, come and tell us in Slack so we can feature it in future newsletters!