5. Technical Writer, A Decision to Disappear
Toss’s technical writing team argues that documentation is essential context for AI, but manually maintaining thousands of documents is impossible with only three technical writers serving roughly 4,000 people. Their solution is to automate the technical writer’s work by teaching AI the team’s implicit standards and embedding those standards into reusable Skills. The initial system supported document creation and review, but adoption remained low because users still had to install, invoke, and supply information to the AI manually. ## Why Toss Wanted to Automate Technical Writing - Documentation gives AI the organizational context it needs to work effectively. - Toss has approximately 4,000 employees but only three technical writers. - Reviewing documents individually does not scale, especially in a fast-moving organization where features change or disappear before documentation is complete. - The team’s goal to “eliminate technical writers” means transferring routine writing and editing work to AI, not abandoning documentation quality. ## Teaching AI Technical Writing Principles - The team analyzed existing technical writing review comments to identify how writers evaluate documents. - Existing writing guidelines were converted into explicit principles, such as: - Focus each page on one subject. - Present value before implementation details. - Each principle was supplemented with incorrect and correct examples so AI would understand the intent rather than apply rules mechanically. - Common document types were converted into templates. - Templates include: - Instructions explaining what each section should contain. - `(required)` markers for information that must not be omitted. - For example, an ADR template requires an overview, context, considered alternatives, decision, and rationale, while also allowing optional sections such as expected outcomes and related references. ## Skill for Writing New Documents The document-writing Skill reproduces the four stages a technical writer typically follows: - **Clarify the purpose:** Ask about the project, document goal, audience, level of detail, source materials, and expected structure. - **Design the structure:** Use a standard structure or select a relevant template, such as onboarding guides, meeting notes, or PRDs. - **Write the content:** Apply technical writing and MDX rules while using templates as structural guidance. - **Review the draft:** Check for awkward wording, missing information, and other quality issues. The Skill also distinguishes between required and optional template sections: - Required sections remain in the draft even when source information is incomplete. - Missing information is represented with questions or comments rather than guesses. - Optional sections are omitted when there is not enough source material to complete them. ## Skill for Reviewing and Improving Documents - The team initially converted past review comments into a checklist. - This produced poor results: AI overlooked important issues while generating unnecessary comments. - The problem was that good writing follows relatively stable principles, whereas bad writing can fail in many different ways. - The revised workflow lets AI independently: - Read the technical writing principles. - Analyze the document. - Identify violations. - Explain the issue and suggest revised wording. - Perform a final checklist-based review. - Previous review comments are now used as examples of how principles apply, rather than as a rigid list of required findings. - One example principle requires descriptions of parameters or properties to include their meaning, accepted format, and usage example—not merely a type such as `date: string`. ## Low Adoption Revealed a Usability Problem - Despite creating both Skills, the team found that few employees used them. - Users still had to: - Download and install the Skill manually. - Understand CLI-based setup, which was unfamiliar to non-developers. - Remember to invoke the Skill whenever they began writing documentation. - Find and provide all relevant source materials themselves. - The team concluded that improving the AI’s capabilities was not enough; the workflow also had to reduce the effort required from users. The main lesson is that AI-based documentation succeeds only when organizational knowledge, writing principles, and templates are encoded clearly—and when the system is integrated into everyday work so employees do not have to remember to use it or prepare everything manually.
Read original(opens in new tab)