Home »

Write the Docs Newsletter – December 2021¶

Hey everyone,

The year is drawing to a close - thank goodness, if you ask me - and we’re back with the very last edtion of the newsletter for 2021. It’s been a _complicated_ year but not without its highlights - our second year of virtual conferences plus the just-wrapped-up Australia super-meetup. Thanks for being such a great community through it all 💖

One last call for folks who haven’t yet filled out the Salary Survey. We’d love it if you would consider contributing the details of your compensation. It’s all anonymous and the anonymised results are released for free, so everyone in the community can benefit. Fill it out here.

With that, on to our articles from this month!

The work documentation really requires (it’s not all writing!)¶

A plaintive question about how to develop content more efficiently produced a perhaps surprising set of responses. The original poster framed their challenge in terms of research that delays the writing process, but replies tended to point out that research is a key part of creating any documentation. If your research is inefficient – if you’re falling down “useless rabbit holes” as one poster put it – you could consider pruning your sources, or working more from summaries than from long-form reads.

Generally, though, folks agreed that research and other supporting activities form the bulk of the work they do to produce docs – actual writing takes up relatively little time overall. In addition to research, testing/QA, wrangling reviews and tooling, managing content beyond the writing (structure, metadata, etc) all showed up on lists of docs work beyond writing. So maybe when we’re not writing we’re still as efficient as we can be?

Deciding what to work on next¶

What should you do when you aren’t sure what to do next? Many of us have an abundance of pending docs work, but the most important task in your pile depends on the particulars of your situation. If you’re having trouble prioritizing docs tasks, try reading product and engineering plans. These are valuable resources for learning what’s important at your company, and the insights you pick up can inform your priorities in the documentation realm.

Of course, more general suggestions usually have wider applicability, so here’s a handful of other good ideas from the Write the Docs community:

Review help tickets from customers and audit your information architecture to learn about potential gaps in your docs coverage.
Test your toolchain and processes for storing and maintaining docs to find problems you can resolve. You might also find some automation opportunities.
Inspect internal documentation for maintenance issues – internal docs are often created and forgotten.
Create a company style guide, if you don’t already have one, and apply it throughout the docs.
Map or document your team workflows, docs resources and processes, and organization charts.
As time allows, learn a new tool or technology to enrich your skills. For example, you could investigate different ways to communicate concepts, like animation.

One more tip: our June 2021 newsletter included a relevant item about balancing writing new docs with ongoing docs maintenance, which may also be helpful.

Answers to “Why are good docs important?”¶

What is the importance of good documentation? This question can come up a lot - during an interview, project planning, or just a chat with a colleague. Do you have a good answer?

You’ve got plenty of options. For example, that good documentation eases the strain on the support staff or minimizes friction for customers, enabling them to complete tasks quickly. Or even more ideas: that good documentation acts as a sales tool, helping with both advertising and lead generation; it shows product commitment, and helps close profitable deals with potential customers. It’s also valuable internally as a source of truth, allowing everyone in the organization to work smarter rather than harder.

For more on this, Lari Maza discusses good documentation in her article “How to Write Good Documentation”. According to Maza, writers should anticipate customer questions, keep within scope, and expand information with links and images.

Standards in documentation tooling¶

We had a great discussion this month about the fragmentation of docs-as-code tooling, sparked by Fabrizio Ferri-Benedetti’s article. The article talks about the often-fragile docs-as-code toolchains that companies run for themselves. When tools are hard to maintain or don’t work well, they hinder growth, speed, and collaboration. He argues that these problems are caused by systemic issues: we’re missing a standard markup language, universal documentation rendering, and a version control system designed for docs.

Documentation rendering was contentious, but folks saw more promise in the markup idea. DITA is heavyweight; Markdown lets you get on with writing, but is neither standardised nor designed for docs; and the alternatives aren’t widely used. Some community members defended AsciiDoc as meeting all the criteria - it’s interesting that it’s currently going through a standardization process via Eclipse.

The article’s main problem with Git, often expressed by writers as well as developers, is that it is hard to learn. There is a counter-argument to needing a new system: instead, we should take the tools we have, but make them work better for use cases. Perhaps we don’t need a new version control system, but better Git clients designed for docs workflows…

But some folks disagreed with the premise that standardisation will help. Not least because creating new standards can make things worse! And how can we standardise if we don’t have any universal best practices? Perhaps, for docs problems, there is no “one best way” - you’ll always have to adapt your tools to different use cases; sometimes what you really need is the feature set of a Help Authoring Tool like Flare. Or perhaps we should all just give up and use Word? (joking, joking!)

What we’re reading and watching¶

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 read: Over at Tech Crunch, Why DEI programs are failing discusses the shortcomings of DEI programs and how ERGs might be the answer.

A longer read: A little old, but still relevant, last year’s McKinsey and Company’s 2020 report on Diversity and Inclusion concludes that companies investing in DE&I are more profitable than those that are not. You can download the full report at the end of the summary.

For a longer time investment: Check out Diversity Inc Best Practices’ Webinar Recap: Let’s talk Microagressions. In this webinar, the panelists define microaggressions, discuss when they first encountered them, how to respond to them, and what their companies are doing to combat them.

From our sponsors¶

This month’s newsletter is sponsored by Gateway Translations:

Gateway Translations makes it easy for tech writers to get started with localization.

Finding the right translation tool with integrations for easy workflow & file compatibility
Translators with technical backgrounds for 45 languages
Trusted by GitHub, TIBCO, Fortune 500s

Book a free consultation.