This discussion emphasizes A key theme is the importance of cross-functional skills for technical writers, who must act as translators, connectors, and strategists, understanding user empathy and data fluency. The conversation also explores AI readiness in documentation, stressing the need to design content for both human and machine consumption through effective metadata, content models, and modular writing, while acknowledging the continued indispensable role of human technical writers for strategic thinking, storytelling, and ensuring accuracy.
About Quetzalli
Quetzalli Writes is a technical writer and documentation contributor known for her involvement in software documentation and developer experience. She has significant experience in creating software documentation, particularly in areas like DevOps, InfoSec, and IT system administration. Quetzalli is noted for her role as a core maintainer of AsyncAPI Docs, where she volunteers to write periodic updates and contributes to the documentation ecosystem, including initiatives like the Google Season of Docs 2023 and the development of an interactive learning path for AsyncAPI.
She shares insights on technical writing trends, job hunting tips for tech writers, and promotes task-based documentation that helps users understand how product features solve problems rather than just presenting features. Quetzalli also actively engages with the technical writing community through newsletters and blog posts, offering practical advice for creating effective documentation and improving developer experience. Her work emphasizes the importance of feedback loops, consistent messaging, and collaboration across teams to enhance platform user journeys.
In this conversation, we discuss:
Docs as ecosystem concept and its evolution: The ecosystem model initially proposed a holistic, multidisciplinary, and community-centered approach to software documentation, emphasizing collaboration beyond just technical writers to include stakeholders like product developers, experience designers, accessibility experts, SEO specialists, and artificial intelligence. It has evolved to align with designing content around the Ideal Customer Profile (ICP), recognizing that different audiences have unique goals, workflows, and entry points, which syncs with the growing interest in context engineering.
The role of a technical writer in the ecosystem model: Technical writers must develop cross-functional skills to be valuable, acting as translators, connectors, and technical communication strategists who help lateral teams improve products. This involves translating engineering speak and code into user empathy and business impacts, understanding and advocating for user journeys for diverse ICPs, demonstrating data fluency by using documentation analytics to improve ROI, fostering collaboration with various internal teams, developing content strategy across documentation, marketing, and C-suite messaging, displaying versatility in understanding technical aspects of code and tools, and mastering storytelling to craft narratives for internal and external buy-in.
AI readiness of documentation: In the age of AI, documentation needs to be designed for both humans and machines (AI agents, LLM models) to find and reference content. Key aspects include designing effective metadata and linking content along the ICP journey. This starts with mapping tasks and workflows for different audience segments (e.g., partner engineer, SRE, CTO). It also requires adapting content models to define reusable types (e.g., tutorials, troubleshooting guides) that can be personalized for different customer roles and their specific error messages. Furthermore, writing modularly by breaking workflows into concise steps, prerequisites, and error remedies allows for repurposing content and more efficient crawling by chatbots and AI agents. Documentation must be machine-readable with semantic headings, tags, stable IDs, and anchors, and the entire ecosystem should be linked via user journeys and paths, from onboarding to error catalogs and support.
Tackling varied technicality for different personas: When addressing users with diverse technical knowledge, it's crucial to identify different stages of the customer journey (e.g., onboarding, building an application, using an API) and document typical errors and issues encountered at each stage accordingly. For instance, common onboarding errors like license activation or authentication token issues would go into a quick start guide, while API-specific errors related to adding employees or processing payroll would be documented for subsequent stages.
Adding value to API/SDK documentation: A significant challenge is the lack of comprehensive error guidance and troubleshooting paths. Beyond documenting typical errors and resolutions, it is essential to write full-fledged tutorials and guides for more advanced troubleshooting scenarios and to pair each API endpoint with a guide and workflow to provide necessary context.
Lowering cognitive load in technical documentation: To reduce the burden on users, long tutorials or guides attempting too many tasks should be broken down into multiple, smaller tutorials. A best practice is to keep quickstarts and guides completable in less than twenty-five minutes; if longer, they should be chunked further.
Recommended workflow for new documentation projects: The speaker suggests starting with personal research to understand the feature or service, then outlining talking points. Next, consult with product and engineering teams, especially the engineer who built the feature, sharing initial understanding. Ask engineers and PMs what minimal information and typical use cases a first-time user would need, which helps in breaking content into smaller chunks or expanding existing guides.
Essential AI skills for technical writers: Technical writers should get comfortable using various AI products (e.g., Gemini, Claude, ChatGPT) to broaden their mindset. It's vital to stay updated on the latest versions and upgrades of AI tools, understanding advanced functionalities like training agents to perform tasks, rather than using them like a search engine.
Automating technical writing tasks:
Automate: CI/CD automations (link checking, redirects). For content, train AI on designed templates and outlines to automate initial information architecture research and suggest content placement. Automate the first rough draft phase by feeding the AI best practices, outlines, and ICP information to generate multiple variations. This saves time on grunt work, research, and initial strategizing for different customer personas. Also, automate the process of addressing customer friction points by feeding negative feedback into the AI to help shape documentation solutions.
Human Role: While AI handles grunt work and initial drafts, the human writer brings strategic thinking, actual writing skill, and the ability to delight customers by solving problems and reducing friction. Humans are crucial as guardians of the source of truth, capable of strategic and beautiful writing, reasoning, and correcting AI hallucinations.
Getting external feedback: Since technical writers often don't directly interact with customers, they should collaborate with lateral teammates who do, such as salespeople and account executives. Sales teams offer insights into customer struggles and product gaps. Account executives can connect technical writers with customers willing to provide feedback. These interactions should be treated like user testing sessions, with prepared steps, talking points, and questions to guide the live call. Developer relations teams also engage in external conversations.
Strategizing media usage in documentation:
Screenshots: Be strategic by only adding screenshots that illustrate individual, specific steps for building something, rather than generic welcome pages. This ensures value and easier maintenance, as UI changes frequently.
Videos: Use video software that allows dividing videos into individual scenes. Create one scene per step, recording the visual first, then adding the audio voiceover. This approach simplifies updates, as only specific scenes need to be re-edited or re-recorded when UI or steps change, avoiding the need to refilm entire videos or re-record all audio.
Measuring documentation success beyond quantitative metrics: Metrics like page views or time on page can be misleading, as a short time on page could indicate highly concise and effective documentation. Instead, focus on searchability. Technical writers should have access to their documentation's search provider data (e.g., Algolia) to monitor top searches, identifying common customer problems, troubleshooting scenarios, or beginner questions to inform content improvements. Additionally, accessing data from the documentation site's AI bot is crucial, noting typical questions, customer resolutions, and particularly unresolved issues, which point to areas needing content improvement or creation.
The future of documentation and AI: AI is compared to the Industrial Revolution, signifying its permanent presence and ongoing evolution. However, there are limitations to AI, as exemplified by potential regressions in models like ChatGPT 5 compared to previous versions. Human compute power also poses a limit. While automation will continue to evolve, human technical writers remain valuable and needed for their strategic thinking, ability to reason, avoidance of hallucinations, role as guardians of the source of truth, and capacity to write strategically and beautifully.
Share this post