Home »

Write the Docs Newsletter – December 2023¶

Seasons greetings, wonderful documentarians. I hope the approaching end of 2023 is bringing you time to reflect on all the amazing things you’ve accomplished this year. And to make plans to make 2024 even better (and better documented).

The end of the year means the last call for the 2023 Documentation Salary Survey – we close submissions on December 31. The response has been great so far, but we still need more contributions to match our previous best year (2021) and, in particular, we still need to reach more contractors, freelancers, and self-employed documentarians. We know you’re out there! If you’ve already contributed, thank you. If you’ve been putting it off, please click through – most people fill out the form in ten minutes or less. And if you can think of anyone else who could contribute who might not know about it, please share the link: https://salary-survey.writethedocs.org/.

The Australia conference is coming up this week. Ticket sales have closed, but I’m sure there will be many inspirational ideas coming out of the discussions. And the videos should be shared after the conference is finished. For your next conference opportunity, the in-person Portland conference is accepting talk proposals until January 15.

If you’re curious about how Write the Docs keeps going, check out the quarterly update from the Community Board. You’ll learn what our board members are doing behind the scenes to support this valuable community.

For your last newsletter of 2023, we have articles on whether documentarians should specialize or stay general, helpful questions to use when getting information about an upcoming change, a discussion of what technical documentation is, and what you might do after deciding to move on from documenting full-time.

I hope you all have a peaceful end to the year. We’ll be back in February with more exciting ideas.

Documentarians as Specialists or Generalists¶

Last month’s article Doc Team Organization, focusing on managers, provoked a lively discussion about the pros and cons of documentarians being generalists or specialists.

The main positive aspects posted:

Specialists: Writers assigned to specific products learn the product in depth and develop relationships with that product’s team members. Being a specialist may be necessary for more technical products to learn the product fully. Also, the product may require specialized knowledge and expertise.
Generalists: Being a generalist can be more interesting and can back up the entire documentation team. Generalists tend to have a better understanding of the full product line, know the breadth of the customer base, and be able to assist in strategic planning.

The main drawbacks included:

Specialists: After focusing on one product, some technical writers got bored, felt cut off from other writers and their products (“siloed”), or got tired of working with the same product teams.
Generalists: Some felt like they were constantly having to switch focus and get up to speed on new products and the dynamics of associated teams. They felt they were less efficient.

For specialists, reviewing others’ work can be a way to learn about more products. They may need to ask about opportunities for fresh challenges. A hybrid generalist could be a specialist with some products and a backup on other products with enough knowledge to take over quickly if needed.

When interviewing, you may need to consider whether your personal style fits in with the prospective documentation team. Some remarked that a documentation’s team focus depends on the size of the company (and product line), the size of the documentation team, and the product development process.

Helpful Questions for Gathering Information¶

This month’s discussions produced a thoughtful list of questions to help you gather the information you need to create adequate documentation. But before getting to the questions, we should mention a few ideas for communicating your questions to internal stakeholders, like product managers.

If it works with your company’s culture, consider listing the questions in a checklist for product managers to complete and return. To help persuade your product organization to adopt the checklist, compare the number of support tickets for releases with and without complete documentation if possible. If adoption is unlikely, create dedicated Slack channels for sharing information about specific features or releases.

You might also meet with product managers individually to explain the information you typically need and share the questions in a more general way. Individual meetings give you a chance to discuss the communication they can expect from you, any guidance you have for working together on the docs, upcoming initiatives, and plans for recurring meetings.

If you can’t get the information you need any other way, try drafting documentation that covers as much as you know and submitting it for review. Reading incomplete docs helps reviewers understand what is missing. And now… the questions!

Audience-related questions:

Who is the intended audience? What is the audience’s skill or knowledge level?
Where is the intended audience located?
What is the most convenient way for the audience to access the documentation?

Questions about resources for more information:

How can I test the feature or changes myself? What permissions and instructions do I need?
Where can I find the code for the feature or change?
Which engineers can explain or demo the new feature or product updates?
Which Slack channels should I join to stay informed?
Where are existing documents located, including feature specifications, project requirements, and acceptance criteria?
Where can I find any recorded demos, wikis, tickets, and internal documentation about the new feature or changes?
Who is preparing the user training (if we plan to offer it)?

Product-specific questions:

Which parts of the existing product are affected by the new feature or change?
How is the new feature or change being marketed to customers?

Docs logistics questions:

What is the timeline for the release?
Who are the final approvers for the documentation?
Does the content require translation?

What Is Technical Documentation?¶

A recent thread about code documentation evolved into defining what technical documentation is.

In general, technical documentation can encompass many types of documentation for various audiences and various reasons. There seems to be a continuum of the “technical” aspect to technical documentation — from extremely technical (for, perhaps, developers or engineers) to less technical (for, perhaps, non-technical users or people who don’t need the technical information).

Some people considered that technical documentation has to be technical itself. Certain resources (such as Wikipedia) focus on the technical aspect and limit technical documentation to certain types of documents. Other resources (such as the Society for Technical Communication) focus on the audience and consider anything written to explain complex technical topics in simpler terms as technical writing. Some people consider anything in less technical terms as user (or consumer) documentation and not technical documentation.

Very technical documentation can include docstrings (for software), technical examples, schematics (for machines or structures), and specifications, but the primary focus is for a technical audience (such as software developers, engineers, or technical support personnel). Those that manage API documentation consider their work to be technical documentation.

Consumer-focused documentation may describe technical content in simple, non-technical terms. A significant issue is whether or not the “consumer” in question is a technical person. If an engineer needs to start learning about a brand new system, is a document that gives an overview of that new system considered technical documentation? The engineer needs to build up an understanding of the system, but may not ever have to use the system per se.

Basically, the concept of what is technical documentation and the role of technical writers may depend on your work experience and background.

Life After Documenting¶

While it is intellectually engaging, some people may eventually find documentation to be an overly familiar environment that breeds monotony. One person started a discussion on this topic with views shared by many who have spent years explaining complex topics. This community discussion focused on migrating out of documentation and into new professional fields.

The thread revealed diverse experiences and provided a platform for people seeking direction on their next steps. The replies ranged from practical advice to touching experiences, giving a road map for people considering a career change.

Several people advised branching out into related industries like copywriting, tech journalism, instructional design, product management, teaching technical writing, UX writing, developer advocacy, and customer support. The community stressed that documentation skills are transferable, opening various careers.

Advice on self-discovery also flooded in, with decision points such as whether to stay in the tech field or make a clean break, whether to face a potential pay drop, and opinions on pursuing further education. Volunteering and seeking help from professional counselors or coaches were mentioned as important elements in this transitional process.

Success stories arose among the common difficulties. One individual transitioned successfully from technical writing to content strategy and eventually to product management. This story demonstrated the opportunity for progress and fulfillment outside a single profession.

The thread acknowledged the emotional cost of discovering that a job previously valued may no longer coincide with future goals. Others suggested reading books like What Color Is Your Parachute? and Who Moved My Cheese? to help get through such a period of uncertainty.

The community advocated for resilience in pursuing new opportunities, offering support, encouragement, and practical ideas. The thread showed a broad array of opportunities for anyone eager for a change, whether to teaching, content marketing, or even being a motorcycle instructor.