Home »

Write the Docs Newsletter – December 2024¶

Salutations, documentarians. I hope 2024 has been good to you personally and professionally. As the year ends, it’s a good time to make plans for all of the ways we will make the world better, and better documented, in 2025.

If you have ideas for how to help others document better, the Call for Proposals for the Portland 2025 conference is now open. So share your best practices and ideas by January 21, 2025, and start looking forward to seeing what others can bring as ticket sales will open soon.

We’ve also been looking to the future as part of the Write the Docs Community Board. You can see what areas are being covered in the Q4 Quarterly Update.

To plan for the future, it can help to know the present. The Documentation Salary Survey 2024 is still open until the end of the year. The value of the results increases with every additional response, so whether you’re full-time or part-time, employee or a contractor or both, or even if you’re currently between jobs, your response helps!

This month we have articles on how to know what you don’t know, using AI in technical writing, and what sort of browsing pattern to optimize for. I hope they help you start the path to a better 2025 and we’ll be back with more ideas in February.

Uncovering the unknown¶

One of this month’s discussions explored a specific challenge of documenting complex subjects when you don’t have sufficient domain knowledge: figuring out what’s missing. Reviewers often focus on corrections and clarifications but may not mention that you’re omitting essential background or conceptual information.

Asking subject matter experts (SMEs) and product managers for a concept-level review can help. You might also ask reviewers to suggest terminology that you can research to improve your own understanding and help you narrow down what to include and exclude. One documentarian even used an introductory textbook for the subject they were documenting, with the idea that any concepts covered in the textbook could reasonably be excluded from the docs.

Another approach is asking “obvious” questions of SMEs, especially about anything that you don’t understand. The curse of knowledge may cause SMEs to overestimate the domain knowledge of their users or assume that all users share their background. Prompting SMEs to explain what they assume everyone already knows can help unearth gaps that should be documented.

Finally, talk to support and technical sales staff to gather valuable information about user perspectives. Ask what readers need to know to keep them from opening support tickets and what could convince them that the feature is worth adopting or the product worth buying.

AI in technical writing: Balancing innovation with practicality¶

The role of AI in technical communication is generating cautious optimism among some documentarians, as seen in recent discussions within the Write the Docs community. While some were skeptical that generative AI tools could ever provide value, others shared examples of how they were already helping.

AI tools have proved useful for repetitive tasks, such as summarizing product requirement documents, reformatting content into tables, and drafting tutorials for frameworks like Diátaxis. Custom implementations, such as private ChatGPT models, are also enabling advanced use cases such as pattern recognition, content audits, and integrating style guides into editing workflows.

However, challenges remain. AI-generated content often requires extensive manual editing to meet quality standards, particularly when dealing with proprietary or specialized material. The limitations of AI tools, such as context constraints and compatibility issues with closed systems like MadCap Flare, add extra steps that can diminish productivity gains.

Key insights from the community:

AI is most valuable as a tool for “intelligent automation”: enhancing existing workflows rather than replacing human expertise.
Critical thinking is essential when using AI to evaluate its output and adapt it effectively.

Documentarians may want to experiment with AI, share their experiences, and explore how it fits into their unique workflows. By taking a thoughtful and adaptive approach, technical communicators can harness the potential of AI tools while upholding the high standards of their craft.

Should we optimize for searching or browsing?¶

Documentarians may have to determine whether users search or browse for content of interest. What you decide may influence how to focus your resources: SEO and search tools or navigation aids. The resolution to this may depend on your users and what they’re looking for… and also your product interface.

Some users, those who frequently search online for content, may prefer to search through your documentation (for example, spending 70% of their time on search and 30% navigation). Other users may prefer to use your site’s navigation system (for example, 30% search and 70% navigation). Nonetheless, some documentarians assume that searching is the primary method that all users rely on. Some indicate that it’s important to have both methods available for the users to select what they want to do.

Information architecture (IA) helps a docs team to develop content in a structured and comprehensive manner. A navigation methodology can implement the IA of the documentation system. So, if your team has developed a structure for the content, you can use it as a navigation device for your readers. As one person indicated: No documentation should be random pages of text. Readers use the structure to learn relationships between different features, use cases, or topics.

Searching and browsing are complementary actions. The method used by any one person may depend on different factors and users may use both. Offer the best of both to satisfy your readers.

Search-related resources