Home »

Write the Docs Newsletter – November 2021¶

Hi folks! November has somehow rolled around (already??) and it’s that newsletter time of the month again.

As promised last time: I’m super excited to let you know that the Salary Survey is now live. It takes less than ten minutes to complete, so please consider filling it out - you’ll be contributing to a really valuable resource for documentarians. All responses are completely anonymous, and we’re very careful not to publish any personally identifiable information (given the small size of the community). If you’re up for it, fill it out here.

Plus, great news from down under - we’ve just announced the Australia and India meetup will be on December 3rd. This “super-meetup” will be a two-hour event with four fab speakers, and will be free to attend. Sign up for the event here!

And with that, let’s take a look at what everyone’s been discussing on Slack…

Managing when your manager lacks docs experience¶

This month, our documentarians discussed how they have handled differences with a manager who has no experience with documentation. Among those who have worked for managers without a docs background, there were roughly two groups: the manager either deferred to the technical writer’s expertise or did not.

If your manager is in the first category, you’ll likely encounter less heavy-handed supervision, and docs-related disagreements may be rare. If your manager is in the second category, you have a harder path to tread, especially when your manager’s perspective on docs-related tasks doesn’t quite match yours.

In the course of this conversation, we learned a new acronym: HiPPO, meaning “highest paid person’s opinion.” In this context, the HiPPO method means ultimately disagreements between tech writers and managers are resolved according to the more senior person’s opinion, regardless of whether they have docs experience. When you are subject to the HiPPO method, your ability to affect docs-related decisions depends on how firmly you can gain your manager’s trust.

Even when your manager is inclined to trust your ability, you’ll still need to confirm their confidence by doing good work, cooperating with the rest of the team, and meeting deadlines. This approach is the best path you can take with managers who don’t grasp your ability either – demonstrating that you understand and can document complex processes might be the only way you can get traction.

Options for single-sourcing¶

Single-source publishing is a content management technique that lets you use one source of content but publish it to different output formats (“write once, publish everywhere”). It’s not something that every team needs, but it can be super useful if you need to publish to the web and PDFs, or if you have many similar variants on one product. If your team is not “technical” - more specifically if they are unfamiliar with version control software like Git, lack software development skills, or have no way of obtaining the support necessary to implement a docs-as-code approach, component content management systems (CCMS) like Paligo and MadCap Flare might be more suitable.

Regardless of the method you choose, decide on a single-source publishing strategy and consider the advantages and disadvantages of each option to determine which is ideal for your team. Distributed contributions, for example, may be a reason to choose the docs-as-code method. In contrast, if you use Flare or a docs-focused CMS like Knowledge Owl, you’ll find more robust support for reusing articles or snippets. Whatever method or tool you choose, have a plan in place to ensure a successful single-source publishing approach.

Documentation gets respect (or at least attention)¶

Two recent reports highlight the increased attention documentation seems to be getting in the worlds of software development.

The 2021 State of DevOps report from Google Cloud includes data showing the effects of docs quality on devops team performance, and describes practices to improve the quality of your documentation. The report is based on seven years of research and data from more than 32,000 professionals worldwide, focusing on “capabilities and practices that drive software delivery, operation, and organizational performance.” So the focus is not on docs – but the report includes good documentation as one of six findings characteristic of the 26% of teams studied who fall into the highest performing category. This is _internal_ documentation, and its quality has a statistically significant impact on how secure, reliable, and effective a team’s devops practices are. Quality documentation efforts should include critical use cases for products and services, guidelines for updating and editing existing documentation, clearly defined ownership and responsibility for documentation, inclusion of docs as part of the software development process, and recognition of docs work during performance reviews and promotions.

The State of Software Quality API 2021 report from SmartBear similarly points to “accurate and detailed documentation” as a key aspect of the overall success of an API, second only to “ease of use” for API consumers. Disappointingly few survey respondents rated their API docs as “Very Good” – but only 16% of teams include technical writers for their API docs. On the other hand, more than half the respondents contribute to API docs in some way, and 60-70% of respondents work for companies that include a formal API documentation process – but only about half of those companies consider documentation a priority. Respondents cited a range of obstacles to providing quality documentation, but they all fell into the larger category of insufficient resources – time, tools, personnel, budget, and more. On another front, our documentarians who so diligently work with OpenAPI definitions will be happy to read that OpenAPI usage continues high, but GraphQL and AsyncAPI continue to grow in popularity.

What we’re reading and listening to¶

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!

This month’s articles are intersectional. They touch on topics that intersect gender identity and people of color.

A short read: A topic of discussion that’s come up in the Write the Docs Slack, is it ok to address a group of people as “you guys”? Baron Schwartz sums up arguments from the internet and offers some alternatives.

A medium read: In the article Stop Telling Women They Have Imposter Syndrome from the Harvard Business Review, Ruchika Tulshyan and Jodi-Ann Burey talk about the myth of Imposter Syndrome and how it’s disproportionately hurting women of color in the workplace.

A longer read/listen: This year the McKinsey and Company’s Women in the Workplace report highlights that women, while making some gains in the workplace, are still facing challenges when trying to rise to higher levels. This is especially true for women of color. Despite the increase of self-reported white allyship and an increase in DEI initiatives, women of color report continued micro-aggressions in the workplace and little allyship action from their peers.

From our sponsors¶

This month’s newsletter is sponsored by Gateway Translations and JetBrains:

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.

'And what is the use of a book,' thought Alice 'without pictures or conversation?' Tech documentation is also more appealing and easy-to-read when illustrated. What visuals do we insert in our docs? What tools do we use to create and edit them? Help us by taking this survey, and we’ll be happy to share the results with you.

Take the survey