Write the Docs Newsletter – December 2022¶
Hello, lovely documentarians. The end of the year is approaching, which is a wonderful time to reflect on all the things we’ve done in 2022. And to reflect on what to look forward to for next year. I hope your personal list of accomplishments is long and your list of remaining things to do isn’t quite as daunting as mine.
This year, Write the Docs has already organized two conferences and is in the process of a third, the Write the Docs Australia conference. The new ideas may already be flowing there by the time you read this. And there’s still time to contribute to the 2022 salary survey. The results from the survey are always helpful in understanding our industry and each of our places in it.
Looking forward at next year, a venue has been chosen and more details settled for the Portland conference. The conference will once again be in person. If you have ideas you’d like to share, the Call for Proposals is open until the beginning of February. The call is open to documentarians of all stripes, so don’t be afraid to send in your proposal. If you can’t make it to Portland, keep an eye out in the new year for the Call for Proposals for the Atlantic conference, which will be entirely virtual.
We’ll be taking a break from the newsletter in January, but we’ll be back with more insights from the community in February. If you might want to help with this knowledge sharing, we’re looking for someone to join the newsletter team. Ping me at @Aaron Collier on Slack if you’re interested.
Push vs. pull for docs work¶
This month, the Write the Docs community discussed the benefits and drawbacks of two ways to approach docs work: push and pull. In the push approach, a product or development representative reaches out to the documentarian with information about releases and product changes that require docs work. In the pull approach, the documentarian is responsible for monitoring releases and product changes to proactively identify documentation needs.
Users of the pull method said that it’s difficult to keep up with everything you have to monitor, from email and Slack discussions to design documents and code updates. At the same time, you don’t have to wait for others to tell you what needs documenting or rely on their judgment about what information is relevant. Attending team meetings, watching project tracking tools, and reviewing product roadmaps are especially helpful when you follow the pull method.
On the other side of the coin, the push method narrows the range of resources you need to monitor but requires trust and good relationships with those who know the most about the product. Processes for the push method can include regular meetings about documenting planned features with product managers or owners, patterns for getting notified about known docs needs and anticipated updates, and even including documentation in the definition of done for product releases.
Most folks use a combination of push and pull. For example, if you’re responsible for multiple products, you might use pull for some and push for others. If you’re part of the product team, you might have good information about upcoming features but still need to reach out to product managers for details like release timing. In many cases, the docs process may start with a push when someone tells you docs are needed but still require plenty of pull as you work through drafts and reviews.
Getting it right: Constructive criticism¶
When working with other documentarians, it’s useful to be able to criticise constructively. But it can also be stressful! It’s not so nice to present someone else with a flood of comments, marking up every sentence they’ve written.
Trying to give better feedback is hard work, but it’s also worth the effort. If you have colleagues whose writing could be better, they’re not likely to improve without thoughtful criticism. That’s where some useful tips, shared by our community this month, come in.
First up, if you’re faced with a bad piece of writing: Know that giving constructive criticism to help someone else improve it _will_ take longer than just rewriting it yourself. You have to accept that this is an investment of time today, which will only pay off in the long run.
In the same vein, the idea is to help another writer grow. So consider what exact area they need to work on and then focus on that. It may feel less scary to focus on corrections to spelling and grammar, but those comments won’t help your colleague improve if their real issue is wordiness or a lack of clarity.
To help your feedback land well, frame it carefully. Criticise the writing, not the person. For example, try “this sentence isn’t very concise” rather than “you are being very wordy here”. A few comments about the biggest issues in a doc may be more useful (and less painful) than many comments on every minor detail.
While online reviews might seem more efficient, meeting in-person can make it easier to communicate your tone and intent. It may help to think of the two of you writing in collaboration. Rather than you critiquing their work, you are both working together to make the document as good as it can be.
Another technique is to present the contributor with the problem, not the solution. Rather than suggesting a better sentence, you can ask if they can think of any ways to make the sentence shorter or explain the reasons you find it unclear. This helps them practice self-editing and gives them more ownership over the final piece.
Finally, the work isn’t all on your side: the reviewee needs to be open to feedback too. Consider: Do you officially manage/coach/mentor this person or are you a peer? Are they happy to spend a lot of time iterating or do they just want to get this piece published ASAP? You may have a lot to teach, but make sure that your reviewee is ready to learn.
When to create screenshots¶
Best practices for creating and managing screenshots aren’t always the clearest. With the overhead of maintaining screenshots and the potential accessibility concerns they present, many people avoid creating them despite the benefit they can provide. Still, even with the shared aversion, sometimes screenshots are helpful or even necessary.
When determining what to capture in a screenshot, be selective to keep maintenance low. For example, avoid capturing the entire screen when only a small region is enough to help orient users. You might also focus more on screenshots to visualize a conceptual flow. Even consider the screenshot’s value. Is the text already clear or will the screenshot make a procedure more understandable?
If visuals are necessary, tools such as Snagit can help you capture screenshots and record videos quickly and powerfully. Or use a service like Screenshow to help you manage visual content.
Rationalizing the worth of screenshots may seem futile to some who believe that the cost of producing and managing them outweighs their value. As documentarians, it helps to think about users and whether their needs include visual aids. If you’re documenting sophisticated technologies, for example, with even more complex procedures, they may require visuals. But conversely, a less complex technology might not find much value in screenshots as the text might be sufficient.
What we’re listening to and reading¶
The #bipoc group’s been discussing the following materials on diversity, inclusion, and equity. Want to join the conversation? Please join us in the #bipoc Slack channel!
A short listen: On the Defining Diversity podcast, Braswell and Bulchandani discuss the difference between culture fit and culture add.
A medium read: While tech struggles with DEI, the logistics industry is making (slow) progress.
A large read: Zippia shares and analyzes some new diversity in technology statistics.
From our sponsor¶
This month’s newsletter is sponsored by Zoomin:
|
Drag your docs portal out of the stone age! Deliver a unified technical content experience that ensures customers always find what they need. Watch video Before you make a "build vs. buy" decision on your technical content delivery, make sure you understand the long-term implications. Learn more |
|
Interested in sponsoring the newsletter? Take a look at our sponsorship prospectus.
Featured job posts¶
- Technical Writer - Developer documentation, Carted (Hybrid, Sydney NSW, Australia)
To apply for these jobs and more, visit the Write the Docs job board.
Virtual events coming up¶
- 08 December, 18:00 CST (Karlsruhe, DE) - Kann Software-Doku von KI-Unterstützung profitieren?
- 20 December, 08:30 EST (New England and Florida, USA) - Morning Social: Chat about Slack best practices and tips
- 17 January, 08:30 EST (New England and Florida, USA) - Morning Social: Focused conversation for documentarians
- 19 January, 18:00 EST (Toronto, CA) - Write the Docs Toronto
- 31 January, 08:30 EST (New England and Florida, USA) - Morning Social: Focused conversation for documentarians
