tossJun 23, 2026

5. Technical Writer, A Decision to Disappear (opens in new tab)

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.

technical-writingaiprompt-engineeringcli+3

tossJun 23, 2026

6. Beyond Tools: Standards and Responsibility (opens in new tab)

Toss’s commerce domain found that reliable organizational knowledge cannot be created by writing more documents or adding automation alone. Sustainable knowledge management requires clear standards for what should be documented, who owns it, how it is maintained, and which sources can be trusted. The proposed solution combines AI-assisted documentation with domain-level responsibility and company-wide governance. ## The Limits of Writing Alone - A commerce wiki consolidated terminology, onboarding material, code references, and policy documents. - This reduced confusion over terms such as “seller” and “store” and gave teams a shared starting point. - However, product and policy changes happened faster than one Technical Writer could document them. - Important knowledge also appeared in policy changes, temporary experiments, and chat discussions that were difficult to track manually. ## Why Culture and Participation Were Not Enough - The team promoted documentation through: - A weekly “Commerce Wiki News” newsletter - A policy-question channel and bot - AI documentation workshops - A documentation guild - These efforts increased requests, wiki usage, and adoption of official terminology. - Participation rarely continued beyond an individual’s first document because documentation was not part of normal work priorities. - Writers lacked guidance on: - What information to preserve - How much detail to include - Which audience to target - How to verify whether a document was correct - Documentation became sustainable only when it was treated as a team responsibility embedded in existing workflows. ## AI Automation Reveals the Governance Problem - AI now creates draft documents nightly from two signals: - Product deployment and policy-change announcements - Questions that the commerce Q&A bot cannot answer - AI gathers supporting context and produces drafts, while humans verify the evidence and approve them. - This removes the burden of starting documents from a blank page. - Automation also exposed new problems: - Duplicate or overlapping documents - Unclear authoritative sources - Outdated policies being used in bot answers - Difficulty distinguishing current policies from completed experiments - Automation can collect and draft information, but it cannot decide who owns a policy or whether a document should still be trusted. ## Knowledge Standards and Governance - The focus shifted from “How do we create more documents?” to “How do we create knowledge people can trust?” - Toss’s knowledge-management standards state that teams should: - Preserve recurring questions, important decisions, and information needed by newcomers. - Organize knowledge so both people and AI can find it. - Connect documents to work tools such as Q&A bots and GitHub. - Assign owners and review cycles to keep information accurate and current. - Possible classification systems include: - **Technical layers** for teams with clear data or system flows - **Service domains** for teams responsible for multiple service areas - **Functional units** for systems with distinct feature boundaries - Information becomes organizational knowledge only when it helps people understand situations and make better decisions, with sufficient context and verification. ## The Role of the Knowledge Committee - The Knowledge Committee defines and maintains company-wide documentation standards and resolves conflicts between organizational rules. - Unlike a voluntary guild, it has designated members with decision-making authority. - Governance operates at two levels: - The Technical Writing Chapter manages shared standards for sources, ownership, document status, and lifecycle. - Individual domains decide how those standards apply locally, including ownership, update schedules, and retirement rules. - This balance prevents both inconsistent practices across teams and overly centralized rules that ignore local realities. - For example, commerce teams may need separate handling for permanent deployments and temporary experiments so expired policies do not remain authoritative. The practical recommendation is to treat knowledge management as an operating system for the organization, not a documentation project. AI can reduce the effort of capturing knowledge, but clear ownership, review processes, lifecycle rules, and governance are necessary to keep that knowledge reliable and useful.

technical-writingaiautomationknowledge-management+3

tossJun 22, 2026

Why Does Our Team’s Documentation Fail? (2) (opens in new tab)

Documentation succeeds not through individual resolve, but through centralized knowledge, clear purpose, and systems that reduce the fear of being wrong. Interviews across a commerce domain and a server-development chapter show that documentation strategies must match an organization’s existing maturity, audience, and work patterns. AI lowers the cost of writing and sharing knowledge, while also requiring more deliberate document organization. ## Lessons from Early Attempts - The commerce wiki was initially designed as a self-service platform supported by workshops and guilds. - Workshops could encourage a first contribution, but sustaining second, third, and later contributions was difficult. - In the Ads domain, documentation was already strong, so the better approach was to respect existing conventions and help people locate knowledge rather than create another system. - Organizations with little documentation need to build foundational knowledge; organizations with mature documentation need better discovery and maintenance. ## Reducing the Fear of Asking and Writing - Developers often avoid asking questions because doing so publicly reveals what they do not know. - They may also hesitate to publish documentation because they fear their knowledge could be inaccurate. - The team addresses this through: - **“Lee’s Development Consultation Week,”** which normalizes questions and encourages teammates to answer questions Lee cannot address. - **A daily knowledge bot, “Ha,”** which shares short server-development tips automatically. - Correcting or adding to an existing shared post feels easier than writing a complete document from scratch. ## How AI Has Changed Documentation - AI makes it faster to create initial drafts and distribute knowledge through chatbots. - It also enables measurement of knowledge flow, including: - The number of questions asked. - Whether teammates provide answers. - The quality and content of those answers. - The number of new documents and week-over-week growth. - These metrics reveal knowledge gaps and recurring questions without manually reviewing every channel. - AI also creates a need for more detailed internal context than human readers typically require. - Commerce therefore separates: - Central, human-friendly documentation managed by technical writers. - Team-repository documentation containing detailed, team-specific context useful to AI but unnecessary for everyone else. ## Shared Principles and Organizational Differences - Both domains and chapters should centralize knowledge and avoid spreading it across too many channels. - Domains typically: - Connect documentation to products and code. - Change rapidly. - Serve a broad and varied audience. - Chapters typically: - Document conventions, working methods, and professional knowledge. - Change more slowly. - Focus on productivity and capability development. - Have a clearer audience, such as a specific role or discipline. - Domain documentation should be understandable even to non-developers, since developers may also lack context outside their specialties. - Separating guides, capability-based policies, glossaries, and metrics helps different readers find documents suited to their needs. ## Where to Begin - First diagnose the organization’s current documentation maturity by asking what people do when they get stuck: - **Ask coworkers or search chat:** foundational documentation is largely missing. - **Search documents:** assess whether information is easy to find; fill gaps if searches fail. - **Ask an AI or bot:** evaluate whether answers are accurate and whether the underlying documents are complete, current, centralized, and sufficiently contextualized. - Define the specific problem driving documentation, rather than starting with a vague goal. - Begin with a focused need, such as creating a glossary for inconsistent terminology or building references for sharing knowledge with other teams. The practical recommendation is to centralize knowledge, identify the organization’s biggest documentation gap, and build a low-friction system where people can contribute, correct, and consume information without relying solely on personal effort.

technical-writingaiknowledge-managementchatbot+3

tossJun 22, 2026

Why Does Our Team’s Documentation Fail? (1) (opens in new tab)

Documentation often fails not because people lack motivation, but because it depends on individual initiative and lacks clear standards. Interviews with a commerce domain and a server chapter showed that teams struggle to know what to document, how much detail to include, and whether their knowledge is accurate. Both organizations found that consolidating scattered knowledge into a shared system is the essential first step. ## Documentation in Domains and Chapters - **Domains** bring together developers, product owners, and designers around a business area such as commerce or advertising. - Their documentation focuses on product-related knowledge, including policies, terminology, and specifications. - **Chapters** group people with the same profession, such as server or frontend engineers. - Their documentation focuses on shared technical knowledge, conventions, and tools. - Dongjin works on consolidating internal knowledge across commerce and advertising domains, while Hyebin develops the company-wide documentation system “Todoc” and runs a documentation guild in the server chapter. ## Different Starting Points - The commerce domain already had strong awareness of documentation needs. - Members specifically requested terminology guides, policy documentation, experiment records, and API references. - Although writing standards were not clearly defined, people understood which documents would help their daily work. - The server chapter was initially more hesitant. - Members had worked without documentation and had not experienced its benefits directly. - An AI chatbot gave poor answers because its source documents were incomplete or disorganized. - Improving the underlying documents gradually made the chatbot more useful, helping members recognize the value of shared knowledge. ## Interviews Revealed the Real Obstacles - Dongjin interviewed developers to identify knowledge gaps and determine what information should be recorded. - The interviews clarified the organization’s needs, even though solving those needs required additional work. - Hyebin initially reviewed onboarding documents very thoroughly and repeatedly reminded people to complete them. - Interviews showed that contributors generally appreciated external review because it improved document quality. - The main problem was not a lack of motivation, but uncertainty: - What knowledge should be included? - How much detail is appropriate? - Is the information accurate enough to share? - These findings shifted the focus from persuading people to write toward making documentation easier and safer to produce. ## Problems Caused by Missing Documentation - In a domain, scattered policies create collaboration bottlenecks. - A team modifying a feature may first have to search for the policy owned by another team. - Newcomers struggle to understand what they do not know, creating prolonged “unknown unknowns.” - In a technical chapter, engineers often need to reconstruct the history behind unusual code. - They search old chat threads, try multiple keywords, or contact the original author. - More time may be spent assessing context and risk than implementing the change itself. - Useful knowledge often remains private. - Engineers may assume everyone already knows it or worry that it is too trivial to share. - As a result, people repeatedly solve the same problems independently, reducing overall productivity. ## Why Documentation Does Not Continue - Documentation benefits the future, while current work usually feels more urgent. - It is often treated as secondary work that requires a deliberate decision to begin. - Authors may also feel responsible for maintaining documents indefinitely. - Without documentation embedded in normal workflows, every update depends on personal willpower. - AI tools can reduce the effort of drafting and maintaining documents, but unclear standards and fear of being wrong remain significant barriers. Both organizations reached the same starting point: gather scattered knowledge in one accessible place, then integrate writing, review, and updates into everyday work rather than relying on individual motivation.

technical-writingknowledge-managementdocumentationapi-documentation+2

tossJun 19, 2026

Creating a Role That Never Existed in the World (opens in new tab)

Technical Writing at Toss has evolved from producing documents to designing organizational knowledge systems. The core argument is that code captures outcomes but not the context, decisions, and history behind them—information that both employees and AI need. Toss’s Technical Writing Chapter therefore aims to make knowledge discoverable, structured, and increasingly self-sustaining, with the long-term goal of making the chapter unnecessary. ### Why Code Alone Is Not a Sufficient Source of Truth - Code records what a system does, but rarely explains: - Why it was designed that way - Which alternatives were considered - What organizational history shaped the decision - Employees often reconstruct context from colleagues’ memories or years-old messenger threads. - AI faces the same problem: it understands general knowledge but lacks an organization’s internal context. - A true Single Source of Truth requires both the code and the surrounding knowledge that explains it. ### From Writing Documents to Bringing Knowledge to People - Early work focused on creating onboarding documentation for the frontend chapter. - The team recognized that well-written documents are ineffective if people do not actively read or find them. - Toss created “Parkssi,” a chatbot integrated into messaging tools and IDEs: - Users ask questions conversationally. - Answers are based on existing documents. - Sources are provided for verification. - Instead of requiring employees to search for documents, the knowledge reaches them where they work. - Teams that previously ignored documentation began requesting similar systems to reduce repetitive questions and capture implicit knowledge. ### From Documents to Knowledge Systems - A knowledge system collects scattered information from code, conversations, deployments, and other sources. - It structures that information so both humans and AI can understand and use it through questions and automation. - Properly designed systems: - Increase productivity across the organization - Reduce communication costs as the company grows - Help employees adapt quickly and consistently - Toss defines knowledge as verified information that helps people understand situations, make better decisions, and act within a specific context. ### The Four Responsibilities of Toss’s Technical Writing Chapter - **Build products:** The chapter develops and operates “Todok,” an internal knowledge-management platform. - **Lead organizational documentation:** TWs work directly with teams to collect and organize knowledge according to each group’s needs. - **Automate Technical Writing:** AI workflows and automation help employees create and review documentation with consistent quality. - **Shape documentation culture:** The chapter runs company-wide sessions, documentation guilds, and knowledge committees focused on making knowledge easier for AI and people to use. ### A Broader Definition of the Technical Writer - Although the job title remains “Technical Writer,” the role now resembles a knowledge-infrastructure designer. - The role expanded by following organizational problems rather than staying within a fixed professional boundary. - The chapter’s ultimate goal is for teams to create and manage knowledge independently, eliminating the need for a dedicated TW chapter. - The series will explore Toss’s knowledge product, failed documentation approaches, automation of TW work, and the path toward self-sufficient organizations. Technical writers can create greater value by designing systems that make knowledge continuously available—not merely by writing more documents. As AI reshapes every profession, expanding a role around the problems it must solve is presented as an opportunity for any discipline.

technical-writingknowledge-managementchatbotdocumentation+3

figmaMar 3, 2025

Why Everyone Can (and Should) Be a Great Storyteller | Figma Blog (opens in new tab)

The article argues that storytelling and writing are not specialized talents reserved for professional writers; they are skills anyone can develop. Clear communication helps turn technical ideas, product plans, and design decisions into shared understanding and action. The difference between “good” and “bad” writers is largely practice, feedback, and willingness to revise—not innate ability. ## Why Storytelling Matters at Work - Strong products, designs, and ideas depend on people who can explain: - Why something should exist - Who it serves - How it improves people’s lives - Writing helps teams bridge the gap between imagination and execution. - At Figma, engineers write technical proposals, designers explain their decisions, and product managers create PRDs to align teams. - Companies such as Microsoft and Slack also use writing to encourage deep thinking, clear communication, and buy-in. ## Challenging the “Bad Writer” Myth - Many people mistake their rough first drafts for the polished writing they read elsewhere. - Every writer begins with imperfect work; improvement comes through: - Feedback - Editing - Deliberate practice - Writing is described as organized thinking: putting ideas on paper can clarify problems and lead to better decisions. - The ability to think clearly is a foundation for becoming a better writer. ## Overcoming the Blank Page - Speaking an idea aloud or explaining it to someone else can reveal a clearer, more natural structure. - Reading widely—including books, magazines, product packaging, and online discussions—helps develop writing ability. - Leslie Lamport’s observation captures the central lesson: without writing, people may only think they are thinking. The practical recommendation is to treat writing as a learnable muscle: read often, write imperfect drafts, seek feedback, and use storytelling to make ideas understandable and actionable.

technical-writingdesign-thinkingproduct-managementstorytelling+2