Episode Summary:
Liz Argall, a seasoned technical writer who has worked with companies like Microsoft and Meta, to delve into the essentials of technical writing. The discussion covers strategies for structuring documentation using frameworks like Diátaxis, leveraging reusable content, collaborating effectively with developers, and the transformative impact of AI on the technical writing role.
Key Topics & Timestamps
Introduction to Technical Writing: Liz explains that the core theme of their life—supporting people in achieving their goals—aligns perfectly with technical writing, which helps users from troubleshooting to gaining deeper process understanding. Liz asserts that technical documentation is crucial for equity and equality.
Qualities of Delightful Documentation: Good documentation, much like good design, should evoke a positive physical and emotional response in users. Effective documentation needs a clear architecture and a clean aesthetic, with a landing page that immediately communicates “why they should care”. Liz shares the practice of using informal language, case studies, and common user questions at the top of support docs to connect with users and align with how people naturally query information (benefiting LLMs).
Determining the Level of Technicality: It is essential to understand “wayfinding” and define your “lane” when setting the technicality level, providing the right level of “breadcrumbs” without overstepping scope (e.g., offering debug info without instructing on contacting an ISP). Liz uses the Diátaxis framework to efficiently chunk information based on user needs:
Tutorials: Taking the user step-by-step.
How-tos: Concise “recipe cards”.
Reference: Clear, precise information (like conversions).
Explanation: Deeper background on underlying concepts.
Challenges and Strategic Reusable Content: Liz cautions technical writers against getting “lost in the tooling” of documentation frameworks, which can disconnect them from the end-user experience. Reusable content involves marking consistent, self-contained chunks of information in a central repository so that a single change updates all embedded instances. The strategic use of reusable content will become more critical because AI and LLMs have limited context and require clear, self-contained information.
Assessing Documentation Maturity: Documentation maturity is connected to organizational development, referencing the “forming, storming, norming, performing” framework for teams. Mature documentation requires a continuous quality improvement process, a clear understanding of the user experience, and a commitment to inclusive content that caters to a global audience, especially in complex fields where English may not be the primary language.
Qualitative and Quantitative Analysis: Liz uses a “search term analysis” framework to evaluate how effectively documents address user pain points and questions, checking results through both on-site and Google searches. This technique helps identify issues like broken links and demonstrates a deep understanding of the user experience.
Collaboration with Developers and Product Implementation : Effective collaboration requires the technical writer to first understand the organization’s voice, vision, style guides, and mission statement. Liz advocates for an “embedded” approach, working closely with developers from the planning stages and reading PRDs. A background in quality assurance (QA) testing provides a systematic way to explore products, focusing on the “golden path” and identifying areas for improvement. This foundational work provides developers with a baseline to initiate a generative conversation.
Documentation should help shape the product and work closely with development, but it should never be ahead of product implementation due to unexpected changes. Liz references Halo Infinite‘s launch as an example of extremely mature software development where structured internal processes (like code lock) enabled mature documentation with actual sign-off processes.
Touchpoints for Solo Technical Writers: Solo writers should make themselves as valuable and integrated as possible, especially given the current climate where LLMs might automate some tasks. Recommended starting points:
Read and absorb the company’s voice, design, and mission statement.
Talk to QA teams, who are a “gold mine” for finding escalation points and touching the documents intimately.
Proactively track announcements from feature heads and schedule meetings to align on deadlines, fostering a consistent documentation cadence.
Ownership and Sign-off: Acquiring sign-off is a major challenge in less mature organizations. Liz prefers to be the “gatekeeper of quality” and “facilitator of process,” while ensuring someone else (the Directly Responsible Individual or owner) owns the document on paper to ensure accountability. For public-facing pages, an internal playbook that acts as a “rolodex” of expertise is recommended to map out who to contact for specific issues.
AI in Technical Documentation: Liz sees AI primarily as an “analysis tool” that can summarize content, allowing writers to evaluate if their document accurately conveys its intended message. Tools like Acrolinx (an earlier AI generation) serve as powerful content governance tools for consistency and adherence to guidelines at scale. Generative AI and LLMs can help overcome the “tyranny of the blank page” by creating consistent outlines and templated experiences for replicable content. Liz is excited about using tools like Retrieval Augmented Generation (RAG) to enhance search functions and help prioritize fixing high-priority doc strings.
The Evolving Role of Technical Writers: The technical writing industry is changing, and the role’s scope often depends on the organization’s size. Liz mentions Fabriio Benedetti’s concept of “technical therapists” who coach others to achieve documentation. Liz hopes the industry will mature, allowing writers to have career trajectories similar to programmers. Technical writers should be seen as “accelerators” who improve the user experience rather than “handbrakes”.
Motivation and Resources: A key motivator for Liz is the opportunity to learn something new. Liz enjoys connecting with people who are passionate about specific topics (”fandoms”) and making their experiences inclusive and fun.
Guest Resources
Website/Blog: https://lizargall.github.io/docs/intro/ (includes a “media I’m enjoying” section).
Connect: Liz encourages listeners to connect on LinkedIn and subscribe to their newsletter.
