toss2026년 6월 23일

5. Technical Writer, 사라질 결심 (새 탭에서 열림)

AI 시대에 문서는 조직의 맥락을 AI에 전달하는 핵심 수단이므로, AI가 문서를 잘 만들고 관리하도록 문서화 원칙과 사례를 학습시켜야 한다. 토스는 소수의 Technical Writer(TW)만으로 수천 명의 문서를 관리할 수 없다는 문제를 해결하기 위해, TW의 역할을 AI Skill로 자동화하려 했다. 하지만 Skill을 만들어 공개하는 것만으로는 사용률이 높아지지 않았고, 사용자가 직접 설치·호출하고 자료를 준비해야 하는 불편함이 주요 장애물로 드러났다. ## AI에게 TW의 암묵지 전달하기 - 기존 TW의 리뷰 코멘트를 분석해 문서를 바라보는 관점과 테크니컬 라이팅 원칙을 추출했다. - 기존 가이드를 AI가 기계적으로 적용하지 않도록 각 원칙에 다음을 함께 제공했다. - 잘못된 예시 - 올바른 예시 - 왜 그렇게 작성해야 하는지에 대한 설명 - 자주 작성하는 문서 유형별 템플릿을 만들었다. - ADR 템플릿에는 다음과 같은 필수 섹션을 명시했다. - 개요 - 맥락 - 고려한 선택지와 장단점 - 최종 결정 - 결정 근거 - 반드시 들어가야 하는 섹션에는 `(required)`를 붙여 AI가 핵심 정보를 누락하지 않게 했다. - 문서 유형과 템플릿을 함께 제공해 AI가 구조와 작성 목적을 이해하도록 했다. ## 문서 작성 Skill 구축 TW가 문서 작성을 지원하는 과정을 네 단계로 분해해 AI Skill에 반영했다. - **목적과 배경 확인** - 서비스·프로젝트명 - 문서 목적 - 대상 독자 - 필요한 상세 수준 - 참고 자료 - 예상 문서 구조를 질문한다. - **문서 구조 결정** - 템플릿이 없으면 개요, 핵심 내용, 부가 정보 순서로 기본 구조를 만든다. - 적합한 템플릿이 있으면 온보딩 가이드, 회의록, PRD 등 문서 유형별 템플릿을 참고한다. - **본문 작성** - 테크니컬 라이팅 원칙과 MDX 규칙에 따라 내용을 채운다. - 템플릿은 문서의 목적과 유형에 맞을 때 보조적으로 사용한다. - **점검** - 어색한 표현이나 누락된 정보를 확인한다. - 필수 정보가 부족하면 추측하지 않고 질문이나 주석으로 남긴다. - 선택 항목은 근거 자료가 없을 경우 빈 섹션으로 만들지 않는다. 사용자는 AI가 묻는 질문에 답하기만 하면 되므로, TW와 대화하듯 문서 초안을 완성할 수 있도록 설계했다. ## 문서 리뷰 Skill의 시행착오 처음에는 기존 리뷰 코멘트를 체크리스트로 바꿔 AI가 모든 항목을 점검하게 했다. 그러나 AI가 중요한 문제는 놓치고, 실제로 필요하지 않은 코멘트를 억지로 생성하는 문제가 발생했다. - 잘 작성된 문서의 기준은 어느 정도 정형화할 수 있다. - 반면 잘못된 문서의 문제는 문서마다 다르게 나타난다. - 목적은 명확하지만 논리 흐름이 어색한 경우 - 논리는 자연스럽지만 독자에게 전달할 가치가 빠진 경우 - 따라서 고정된 체크리스트만으로는 다양한 문서 문제를 효과적으로 찾기 어려웠다. 이를 해결하기 위해 AI가 원칙을 참고해 자율적으로 판단하는 리뷰 워크플로를 만들었다. - 테크니컬 라이팅 원칙 파일을 먼저 읽는다. - 문서를 원칙에 비추어 스스로 검토한다. - 문제라고 판단한 이유와 수정 초안을 코멘트로 작성한다. - 마지막에 체크리스트로 누락을 한 번 더 확인한다. 기존 리뷰 코멘트는 단순 점검 목록이 아니라, 원칙이 실제 문서에 어떻게 적용되는지 보여주는 예시로 활용했다. 예를 들어 `date: string`처럼 이름과 타입만 적는 대신, 의미·허용 형식·사용 예시까지 함께 작성하도록 가르쳤다. ## Skill만 공개해서는 충분하지 않았다 두 가지 Skill을 만들어 사내에 공개했지만, 기대만큼 사용되지 않았다. - 사용자가 직접 Skill을 다운로드하고 설치해야 했다. - 비개발자에게 CLI 기반 설치 과정이 낯설고 어려웠다. - Skill을 설치한 뒤에도 문서를 작성할 때마다 사용자가 AI Skill을 떠올리고 직접 호출해야 했다. - 문서 작성에 필요한 코드, 기획서, 기존 문서, Slack 링크 등의 자료도 사용자가 직접 찾아 AI에게 전달해야 했다. - 결국 자동화된 기능이 있어도 실제 업무 흐름과 분리되어 있으면 사용자가 추가로 수행해야 하는 일이 많았다. 따라서 문서 자동화의 핵심은 좋은 프롬프트나 Skill을 만드는 데서 끝나지 않는다. 사용자가 별도로 설치하거나 기억하거나 자료를 수집하지 않아도, 실제 업무 과정에서 자연스럽게 AI가 문서 작성과 리뷰를 지원하도록 연결해야 한다.

technical-writingaiprompt-engineeringcli+3

toss2026년 6월 23일

6. 도구를 넘어, 기준과 책임으로 (새 탭에서 열림)

커머스 조직의 지식 관리는 문서를 많이 쓰거나 자동화 도구를 도입하는 것만으로 완성되지 않는다. 무엇을 지식으로 남길지, 누가 책임질지, 어떤 문서를 신뢰할지에 대한 기준과 거버넌스가 함께 있어야 한다. 궁극적으로는 개인의 기억과 흩어진 기록을 조직의 업무 흐름 속에서 생성·검증·갱신되는 시스템으로 바꿔야 한다. ## 혼자 문서를 작성하는 방식의 한계 - 커머스 위키에 용어사전, 온보딩 문서, 정책 문서를 정리하자 팀마다 다르게 쓰던 용어를 통일하고 다른 팀의 기능을 이해하는 출발점을 만들 수 있었다. - 하지만 제품과 정책의 변화 속도가 문서 작성 속도보다 빨랐다. - 담당자가 바뀐 정책, 일시적인 실험, 메신저에서 논의된 결정까지 한 사람이 모두 추적하기는 불가능했다. - 지식이 현장에서 먼저 생기고 TW가 뒤늦게 정리하는 구조로는 최신성을 유지하기 어려웠다. ## 참여를 유도하는 문화만으로 부족했던 이유 - 주간 뉴스레터, 정책 질문봇, 문서화 워크숍, 길드 등을 통해 구성원의 참여를 높였다. - 문서 요청과 위키 인용은 늘었지만, 첫 기여가 지속적인 기여로 이어지지는 않았다. - 문서 작성은 업무 우선순위에서 밀렸고, 작성된 문서도 시간이 지나며 갱신되지 않았다. - 문서의 적절한 깊이와 대상 독자가 정해져 있지 않아 작성자가 매번 혼자 판단해야 했다. - 실무자는 상세한 구현 정보가 필요하지만, 다른 팀에는 불필요한 노이즈가 될 수 있다. - 개발자에게 유용한 변수명과 기술 세부사항은 비개발자의 이해를 방해할 수 있다. - 문제는 구성원이 문서화에 무관심해서가 아니라, 무엇을 어디에 어느 수준으로 남기고 누가 검토할지 정해져 있지 않았다는 데 있었다. - 문서화가 업무 흐름에 포함되고 팀의 책임으로 인정되어야 지속될 수 있다. ## AI 자동화가 보여준 구조적 문제 - 매일 밤 AI가 두 가지 신호를 바탕으로 문서 초안을 작성한다. - 배포·정책 변경 공지에서 문서 갱신이 필요한 내용을 추출한다. - 정책 질문봇이 답하지 못한 질문을 찾아 관련 자료를 바탕으로 새 문서 초안을 만든다. - 사람은 빈 화면에서 처음부터 작성하는 대신, AI 초안의 근거를 확인하고 승인하는 역할을 맡는다. - 자동화로 작성 부담은 줄었지만 새로운 문제가 드러났다. - 비슷한 문서가 중복 생성됐다. - 최신 문서가 무엇인지 판단하기 어려웠다. - 종료된 실험이나 오래된 정책을 AI가 현행 정책처럼 답하는 경우가 생겼다. - 자동화는 지식 수집과 초안 작성은 돕지만, 문서의 신뢰성·최신성·책임자를 결정하지는 못한다. ## 지식 거버넌스와 책임의 필요성 - 질문의 초점이 “문서를 어떻게 만들까?”에서 “어떻게 믿을 수 있는 지식을 만들까?”로 바뀌었다. - 정책 담당자 변경, 오래된 결정의 폐기, 중복 문서 간 우선순위 같은 문제는 도구가 아니라 운영 기준이 해결해야 한다. - 토스는 문서와 지식을 누가, 언제, 어떤 기준으로 만들고 관리하고 폐기할지 이해관계자가 함께 정하는 ‘커머스 문서·지식 거버넌스’를 제안했다. - 거버넌스는 한 번 정하고 끝나는 규칙이 아니라, 실제 적용 결과를 확인하고 지속적으로 보완하는 체계다. ## 토스 팀의 지식 관리 기준 - **아는 것은 조직에 남긴다** - 반복해서 묻는 질문 - 중요한 의사결정 - 새로 온 구성원이 알아야 하는 내용 - **남긴 지식은 찾을 수 있게 정리한다** - 사람이 검색하거나 AI가 참조할 수 있도록 분류·구조화한다. - 조직 특성에 따라 다음 기준을 선택할 수 있다. - 기술 레이어: 데이터나 시스템의 처리 단계 - 서비스 도메인: 담당 서비스 영역 - 기능 단위: 시스템 또는 기능별 구분 - **필요한 순간에 사용할 수 있게 연결한다** - 위키에 저장하는 데 그치지 않고 질문봇, GitHub 등 실제 업무 도구와 연결한다. - **정확한 정보를 최신 상태로 유지한다** - 문서 책임자와 검토 주기를 정한다. - 실험 정책과 확정 정책을 구분하고, 종료된 정책은 폐기하거나 기록용으로 분류한다. - 조직의 지식은 단순히 글로 남은 모든 정보가 아니라, 구성원이 상황을 이해하고 더 나은 결정을 내리는 데 도움이 되며 검증된 정보다. ## Knowledge Committee의 역할 - Knowledge Committee는 전사 문서 운영 기준을 정의하고 유지하며, 조직 간 기준 충돌을 조정하는 협의체다. - 자발적 모임인 길드와 달리 공식적인 의사결정 권한과 실행력을 가진다. - 운영은 두 층으로 나뉜다. - **TW 챕터**: 문서의 정의, 상태, 출처, 책임자 등 전사 공통 기준을 관리한다. - **각 도메인·챕터**: 현장 특성에 맞춰 문서의 책임자, 갱신·폐기 시점, 운영 방식을 정한다. - 중앙에서 모든 것을 통제하면 현장 변화에 느리고, 전사 기준이 없으면 조직마다 지식 관리 방식이 달라진다. - 예를 들어 커머스 조직에서 실험 배포와 확정 배포를 구분하지 않으면 종료된 실험 정책이 현행 정책처럼 남을 수 있다. - 이런 예외와 시행착오를 커미티가 기준에 반영하고 전사에 공유하면, 개별 조직의 경험이 전체 조직의 운영 노하우가 된다. ## 개인의 기억을 조직의 자산으로 전환하기 - 목표는 지식이 특정 개인이나 메신저 기록에 머무르지 않고 조직 안에서 계속 축적되고 재사용되는 구조를 만드는 것이다. - 지식을 남기고 검증하고 다시 사용하는 과정이 업무의 기본 흐름에 포함되어야 한다. - TW의 역할도 문서 작성에 머무르지 않고 지식 시스템, 제품, 거버넌스를 설계하는 방향으로 확장된다. - 궁극적으로는 문서화가 별도의 숙제가 아니라 자연스러운 업무 방식이 되어, TW의 개입 없이도 조직 지식이 순환하는 상태를 지향한다. 실무적으로는 도구를 도입하기 전에 먼저 “무엇을 남길 것인가”, “누가 검토하고 책임질 것인가”, “언제 최신성을 확인하고 폐기할 것인가”를 정하는 것이 우선이다. 이후 자동화와 AI를 초안 작성·검색·질의응답에 연결해야 지식 관리 시스템이 지속적으로 작동할 수 있다.

technical-writingaiautomationknowledge-management+3

toss2026년 6월 22일

우리 팀의 문서화는 왜 실패할까? (2) (새 탭에서 열림)

두 조직의 문서화 경험은 자율적 기여만으로는 지식이 지속적으로 축적되기 어렵다는 점을 보여준다. 문서화의 핵심은 흩어진 지식을 한곳에 모으고, 질문과 공유에 대한 심리적 부담을 낮추며, 조직의 상태에 맞는 구조와 운영 방식을 만드는 데 있다. AI는 문서 작성과 지식 전파를 쉽게 할 뿐 아니라, 질문·문서 증가량·답변 품질 등을 지표로 파악하게 해 문서화 상태를 진단하는 도구가 되고 있다. ## 자율적 문서화의 한계 - 커머스에서는 구성원이 자율적으로 참여하는 ‘커머스 위키’를 만들기 위해 워크숍과 길드를 운영했다. - 첫 문서를 작성하게 만드는 데는 성공했지만, 두 번째·세 번째 기여로 이어지게 하기는 어려웠다. - 문서화가 개인의 의지와 자발성에만 의존하면 지속 가능한 운영 구조를 만들기 어렵다. - 반면 이미 문서가 잘 갖춰진 애즈 도메인에서는 새 플랫폼을 만들기보다 기존 컨벤션을 존중하고, 지식의 위치와 연결 관계를 파악하기 쉽게 만드는 데 집중했다. - 문서가 거의 없는 조직과 이미 충분한 문서가 있는 조직은 출발점과 우선순위가 달라야 한다. ## 지식 공유를 막는 심리적 부담 - 질문을 적게 하는 이유는 단순히 관심이 부족해서가 아니라, “내가 모른다”는 사실을 공개하는 것이 부담스럽기 때문이다. - 문서를 작성할 때도 “내 지식이 틀리면 어떡하지”라는 불안 때문에 좋은 자료를 공유하지 못하는 경우가 많다. - 이를 해결하기 위해 ‘개발 상담 주간’을 열어 질문 자체를 자연스러운 행동으로 만들었다. - 특정 전문가에게 자유롭게 질문하도록 유도 - 다른 사람의 질문에 공감하도록 장려 - 전문가가 답하지 못한 질문에는 팀원들이 대신 답변하도록 독려 - 매일 짧은 서버 개발 지식을 전달하는 봇도 운영한다. - 구성원이 직접 문서를 찾지 않아도 지식에 노출된다. - 완성된 문서를 처음부터 작성하는 대신, 공유된 내용에 한마디를 보태거나 수정하는 방식으로 참여 장벽을 낮춘다. ## AI가 낮춘 문서화의 진입장벽 - AI를 이용하면 문서 초안을 빠르게 만들 수 있어 문서 작성에 필요한 부담이 줄어든다. - 챗봇은 매일 지식을 전달하거나 질문에 답하면서 지식 공유를 일상적인 활동으로 만든다. - AI는 문서화 현황을 정량적으로 확인하는 데도 활용된다. - 챗봇에 올라온 질문 수 - 사람이 대신 답변한 사례와 답변 내용 - 일주일 동안 새로 작성된 문서 수 - 지난주 대비 문서 증가량 - 새로 추가된 문서 목록 - 이를 통해 어떤 지식이 부족한지, 구성원이 무엇을 궁금해하는지, 지식이 실제로 순환하고 있는지를 파악할 수 있다. ## 사람용 문서와 AI용 세부 문서의 분리 - AI가 문서를 읽게 되면서 사람에게는 불필요한 세부 맥락까지 기록해야 하는 상황이 생겼다. - 커머스에서는 문서를 두 영역으로 나누었다. - 중앙 문서: Technical Writer가 관리하며 사람이 읽기 쉽고 조직 전체에 공유할 만한 내용 중심 - 팀 저장소 문서: 업무 과정에서 자동으로 쌓이며 팀 내부 AI가 활용할 수 있는 세부 정보와 맥락 포함 - 문서의 독자가 사람뿐 아니라 AI까지 확장되면서, 문서의 목적과 공개 범위를 구분하는 구조가 필요해졌다. ## 도메인과 챕터의 차이 - 공통 원칙은 지식을 한곳에 모으고, 문서가 흩어지지 않도록 통로를 단순화하는 것이다. - 도메인 문서 - 제품과 코드에 직접 연결된다. - 제품 출시와 변화가 빠르므로 문서 업데이트 주기도 짧다. - 용어, 기능, 정책, 지표처럼 업무와 직접 관련된 구조가 중요하다. - 독자가 다양하므로 비개발자도 이해할 수 있는 수준으로 작성하는 것이 효과적이다. - 챕터 문서 - 특정 직군을 위한 컨벤션, 업무 방식, 생산성 지식이 중심이다. - 코드와 직접 관련되지 않은 추상적인 내용이 많다. - 변화가 느린 만큼 지속적인 업데이트와 참여를 유도하는 방식이 과제다. - 독자가 비교적 명확해 목적에 맞춘 문서 작성이 쉽다. ## 문서 유형과 독자 구분 - 하나의 문서에 모든 정보를 담기보다 독자와 목적에 따라 문서를 분리해야 한다. - 활용 예시는 다음과 같다. - 가이드: 업무를 수행하는 방법 설명 - 기능 단위 정책: 제품이나 기능의 동작 원칙 정리 - 용어 사전: 조직 내 공통 언어 정의 - 지표 문서: 기능이나 정책을 측정하는 기준 설명 - 문서 유형별 역할을 명확히 하면 독자가 필요한 정보를 더 빠르게 찾을 수 있다. ## 문서화 수준 진단 방법 - 업무 중 막혔을 때 무엇을 먼저 찾는지 관찰하면 조직의 문서화 수준을 파악할 수 있다. - 사람이나 사내 메신저를 찾는 경우 - 문서가 거의 없는 상태다. - 업무에 가장 자주 필요한 정보부터 하나씩 정리해야 한다. - 문서를 검색하는 경우 - 원하는 정보를 찾지 못한다면 부족한 문서를 보완해야 한다. - 검색이 잘 된다면 문서는 충분히 쌓인 상태이며, AI를 연결해 접근성을 높일 수 있다. - 문서 기반 AI나 봇에게 질문하는 경우 - 답변이 부정확하면 원인을 분석해야 한다. - 관련 문서가 없으면 새로 작성해야 한다. - 정보가 여러 곳에 흩어져 있으면 한곳으로 통합해야 한다. - 문서는 있지만 엉뚱한 답을 하면 내용이 오래됐거나 맥락이 부족할 가능성이 크다. ## 문서화의 구체적인 시작점 - “문서화를 해야 한다”는 막연한 목표보다 실제 문제와 니즈를 먼저 정의해야 한다. - 예를 들어: - 팀마다 용어가 달라 소통이 어렵다면 용어 사전부터 만든다. - 다른 팀이나 외부에 공유할 레퍼런스가 없다면 공통 가이드를 만든다. - 반복적으로 질문이 발생한다면 해당 업무의 절차와 판단 기준을 문서화한다. - 문제를 하나로 좁히고 그 문제를 해결하는 문서부터 시작해야 지속 가능성이 높다. 결국 효과적인 문서화는 구성원의 의지에만 기대지 않고, 지식을 한곳에 모으고 자연스럽게 공유되도록 만드는 운영 구조에서 출발한다. 먼저 조직의 현재 상태와 가장 큰 문서화 니즈를 진단한 뒤, 하나의 구체적인 문제를 해결하는 문서와 자동화부터 시작하는 것이 좋다.

technical-writingaiknowledge-managementchatbot+3

toss2026년 6월 22일

우리 팀의 문서화는 왜 실패할까? (1) (새 탭에서 열림)

문서화가 실패하는 이유는 구성원의 의지 부족보다 문서 작성이 개인의 결심에만 의존하는 구조에 있습니다. 무엇을 어디까지 써야 하는지 기준이 없고, 지식의 정확성을 확신하기 어렵고, 문서화가 업무 프로세스에 자연스럽게 포함되지 않기 때문입니다. 도메인과 챕터 모두에서 출발점은 흩어진 지식을 한곳에 모아 실제 업무에 활용되도록 만드는 것이었습니다. ## 도메인과 챕터의 문서화 차이 - **도메인** - 커머스·광고처럼 특정 사업이나 제품을 목표로 여러 직군이 협업하는 조직입니다. - 정책, 용어, 제품 지식, 실험 결과, API 등 업무와 직접 연결된 정보를 다룹니다. - **챕터** - 서버·프론트엔드처럼 같은 직군이 모인 기능 조직입니다. - 컨벤션, 도구 사용법, 기술 표준, 운영 경험 등 직군 공통 지식을 공유합니다. ## 조직별 문서화 활동 - 동진 님은 커머스와 애즈 도메인에 흩어진 내부 지식을 연결하고, 개발자센터와 문서 업데이트 프로세스를 운영합니다. - 혜빈 님은 전사 문서화 기준과 문서 시스템 ‘토독’을 만들고, 서버 챕터에서는 문서화 길드를 운영합니다. - 문서 작성뿐 아니라 문서 리뷰, 자동화, 지식 공백 탐색까지 문서화의 범위를 넓히고 있습니다. ## 조직의 기대와 실제 반응 - 커머스 도메인에서는 구성원들이 이미 구체적인 문서화 요구를 갖고 있었습니다. - 용어가 통일되지 않아 불편함 - 제품에 적용 중인 정책을 찾기 어려움 - 실험 문서와 API 문서가 제대로 정리되지 않음 - 서버 챕터에서는 처음에 문서화의 효용보다 작성에 드는 수고를 더 크게 느꼈습니다. - 문서를 기반으로 답변하는 AI 챗봇도 원천 문서가 부실해 효과가 제한적이었습니다. - 이후 문서화 길드가 챗봇의 답변을 모니터링하고 부족한 문서를 보완하면서, 문서가 실제 도구의 품질을 높인다는 점을 구성원들이 체감하게 됐습니다. ## 인터뷰로 확인한 실제 문제 - 동진 님은 구성원 인터뷰를 통해 도메인에서 필요한 지식과 문서 공백을 파악했습니다. - 혜빈 님은 온보딩 문서 리뷰가 작성자에게 부담이 되는지 확인하기 위해 인터뷰를 진행했습니다. - 예상과 달리 구성원들은 리뷰를 긍정적으로 받아들였습니다. - 공개 전 다른 관점에서 검토할 수 있음 - 초안보다 문서 품질이 향상됨 - 문서화의 핵심 장애물은 의지 부족이 아니라 작성 방법의 불확실성이었습니다. - 무엇을 다뤄야 하는지 모름 - 어느 수준까지 작성해야 하는지 모름 - 자신의 지식이 정확한지 확신하기 어려움 - 틀린 정보를 공유할까 봐 공개를 꺼림 ## 문서가 없을 때 발생하는 협업 비용 - 도메인에서는 정책과 정보가 여러 팀에 흩어져 협업이 지연됩니다. - 예를 들어 B팀이 정산 기능을 수정하려면 먼저 기존 정산 정책의 위치부터 찾아야 합니다. - 온보딩 과정에서도 체계적인 문서가 없으면 자신이 무엇을 모르는지조차 파악하기 어렵습니다. - 챕터에서는 코드만으로 이해하기 어려운 운영상의 예외나 설계 배경을 찾는 데 많은 시간이 듭니다. - 과거 메신저 스레드를 검색하거나 - 여러 검색어로 반복해서 찾거나 - 최종적으로 코드를 작성한 사람에게 직접 물어봐야 합니다. - 개인이 해결한 오류와 업무 지식을 공유하지 않으면 같은 문제를 구성원들이 반복해서 해결하게 됩니다. - “이 정도는 모두 알겠지”, “나만 모르는 것 같다”는 심리적 장벽이 지식 공유를 막습니다. ## 문서화가 개인의 의지에 의존하는 구조 - 문서화는 당장 효과가 나타나기보다 6개월 후, 1년 후에 가치가 커지는 미래를 위한 투자입니다. - 현재 업무와 직접 연결되지 않으면 부수적인 일로 밀리기 쉽습니다. - 문서를 한 번 작성하는 데서 끝나지 않고 지속적인 업데이트 책임도 필요합니다. - 따라서 작성자는 문서화를 가치 있는 자산보다 추가적인 책임이나 부담으로 느낄 수 있습니다. - 작성과 수정이 업무 프로세스에 포함되어 있지 않으면, 바쁜 상황에서 문서화는 쉽게 중단됩니다. - AI는 초안 작성과 정리를 도와 문서화의 도구적 장벽을 낮추지만, 문서화 기준과 운영 구조 자체를 대신 만들지는 못합니다. ## 문서화의 출발점 - 조직에 필요한 문서를 먼저 파악하려면 구성원 인터뷰와 실제 업무의 불편을 관찰해야 합니다. - 완벽한 문서를 한 번에 만들기보다 흩어진 지식을 우선 한곳에 모으는 것이 중요합니다. - 이후 검색, 리뷰, AI 챗봇 등 실제 사용 사례를 통해 부족한 문서를 발견하고 개선해야 합니다. - 문서화가 지속되려면 작성·리뷰·업데이트가 개인의 의지가 아니라 업무 흐름에 자연스럽게 포함되어야 합니다.

technical-writingknowledge-managementdocumentationapi-documentation+2

toss2026년 6월 19일

세상에 없던 직무를 만들어가기 (새 탭에서 열림)

토스의 Technical Writing Chapter는 문서를 작성하는 역할을 넘어 조직의 지식 시스템을 설계하는 조직으로 확장되었습니다. 코드만으로는 설명할 수 없는 의사결정의 맥락과 암묵지를 문서화하고, 이를 사람과 AI가 업무 중 바로 활용할 수 있게 만드는 것이 핵심입니다. 궁극적으로는 문서 작성 자체를 자동화해 TW가 없어도 조직 안에서 지식이 지속적으로 쌓이는 구조를 만드는 것을 목표로 합니다. ### 코드만으로는 완성되지 않는 SSoT - 코드는 시스템이 무엇을 하는지는 보여주지만, 왜 그렇게 설계했는지와 어떤 의사결정을 거쳤는지는 담기 어렵습니다. - 담당자가 자리를 비우거나 퇴사하면 과거 메신저 대화와 개인의 기억에 의존해 맥락을 찾아야 합니다. - AI 역시 일반적인 지식은 잘 활용하지만 조직 고유의 역사와 의사결정 맥락은 알 수 없습니다. - 따라서 진정한 Single Source of Truth는 코드뿐 아니라 코드 주변의 맥락과 히스토리까지 포함해야 합니다. - AI에게 업무를 맡기려면 조직 구성원이 알고 있는 내용을 먼저 구조화해 남겨야 합니다. ### 문서를 쓰는 일에서 지식이 찾아가게 만드는 일로 - 초기에는 프론트엔드 챕터의 온보딩 문서처럼 필요한 내용을 정리하는 데 집중했습니다. - 그러나 좋은 문서도 사람들이 처음부터 읽지 않으며, 필요한 부분만 찾아보는 경우가 많다는 한계가 있었습니다. - 문서 링크를 전달하는 대신, 사람들이 실제로 일하는 메신저와 IDE 안에서 문서 내용을 활용하도록 챗봇 ‘박씨’를 만들었습니다. - 박씨는 기존 문서를 근거로 답변하고 출처까지 제시해, 사용자가 직접 문서를 검색하지 않아도 필요한 지식에 접근하게 했습니다. - 이 시스템을 계기로 문서에 관심이 없던 팀들도 반복 질문을 줄이고 암묵지를 시스템화하기 위해 지식 시스템을 요구하기 시작했습니다. ### 문서에서 지식 시스템으로 - TW의 역할은 문서를 잘 쓰는 사람에서 조직에 맞는 지식 시스템을 설계하는 사람으로 확장되었습니다. - 지식은 특정 맥락에서 문제를 이해하고 더 나은 결정을 내리도록 돕는, 검증된 정보입니다. - 지식 시스템은 코드·대화·배포 기록 등에 흩어진 지식을 한곳에 모으고, 사람이 읽거나 AI가 이해할 수 있는 형태로 구조화합니다. - 이렇게 축적된 지식은 검색뿐 아니라 질문 응답과 업무 자동화에도 활용됩니다. - 조직이 커질수록 반복 질문과 커뮤니케이션 비용이 증가하므로, 지식 시스템은 생산성과 온보딩을 지원하는 조직 인프라가 됩니다. ### Technical Writing Chapter가 하는 네 가지 일 - **지식 플랫폼 개발** - 사내 지식 관리 플랫폼 ‘토독’을 직접 만들고 운영합니다. - **조직별 문서화 주도** - 각 조직의 업무 방식과 필요한 지식에 맞춰 흩어진 정보를 수집하고 활용 구조를 설계합니다. - **문서 작성의 자동화** - AI 워크플로와 자동화를 활용해 구성원이 비슷한 품질의 문서를 작성하고 리뷰받도록 합니다. - 장기적으로 사람이 직접 수행하는 Technical Writing을 줄이는 것이 목표입니다. - **문서화 문화 조성** - AI가 잘 읽을 수 있는 문서 작성법 등을 주제로 전사 세션을 진행합니다. - 조직별 문서화 길드와 지식 커미티를 운영해 지식을 생산하고 관리하는 방식을 바꿉니다. ### 궁극적인 목표: Technical Writer의 소멸 - 올해 목표는 사람이 직접 문서를 작성하지 않아도 조직의 지식이 축적되는 구조를 만드는 것입니다. - TW가 모든 문서를 대신 작성하는 것이 아니라, 조직 구성원과 AI가 지속적으로 지식을 생산·관리하도록 시스템과 문화를 구축합니다. - 최종적으로는 Technical Writing Chapter가 없어도 각 조직이 스스로 지식 시스템을 운영할 수 있도록 만드는 것을 지향합니다. - 이는 직무가 사라진다는 의미보다, 특정 직무에 의존하지 않는 지식 생산 구조를 만든다는 의미에 가깝습니다. ### 다른 직무에도 적용되는 확장 방식 - 이 사례는 정해진 직무를 수행한 결과가 아니라, 조직의 문제를 해결하는 과정에서 직무의 범위를 새롭게 정의한 사례입니다. - AI가 업무 방식을 바꾸는 상황에서는 기존 직무 설명에 머무르기보다 반복되는 문제와 조직의 필요를 따라 역할을 확장할 수 있습니다. - Technical Writer의 전문성은 글쓰기 자체뿐 아니라 지식을 발견하고, 구조화하고, 전달하며, 자동화하는 능력으로 넓어지고 있습니다. 조직의 지식을 개인의 기억이나 메신저 기록에만 남겨두지 않으려면 코드와 맥락을 함께 관리해야 합니다. 문서를 단순한 참고 자료가 아니라 업무 흐름 속에서 바로 활용되는 시스템으로 설계하고, 반복적인 작성과 관리를 자동화하는 방향이 실용적인 접근입니다.

technical-writingknowledge-managementchatbotdocumentation+3

figma2025년 3월 3일

왜 누구나 위대한 스토리텔 (새 탭에서 열림)

좋은 제품과 아이디어는 역할과 관계없이 자신의 비전을 명확히 설명하는 사람에게서 나온다. 글쓰기는 타고난 재능이 아니라 생각을 정리하고 전달하는 능력이며, 누구나 연습과 피드백을 통해 발전할 수 있다. 특히 기술 문서, 디자인 결정, 제품 요구사항처럼 협업이 중심인 업무에서 스토리텔링은 아이디어를 현실로 옮기고 사람들의 동의를 얻는 핵심 도구다. ## “나는 글을 못 쓴다”는 오해 - 많은 사람은 자신의 초안과 전문가의 완성된 글을 비교하며 글쓰기에 소질이 없다고 판단한다. - 그러나 모든 작가는 거칠고 미완성된 초안에서 시작한다. - 좋은 글쓰기와 나쁜 글쓰기의 차이는 재능보다 다음과 같은 태도에서 비롯된다. - 피드백을 받아들이기 - 편집자와 협업하기 - 의도적인 연습을 지속하기 - 글쓰기는 근육과 같아서 시간과 노력을 들일수록 발전한다. - 셰익스피어조차 처음부터 말하거나 쓸 수 있었던 사람이 아니었다는 점은 글쓰기 능력이 후천적으로 길러진다는 사실을 보여준다. ## 지금 스토리텔링이 중요한 이유 - 빠르게 변화하는 환경에서는 깊이 생각하고 이를 명확하게 공유하는 능력의 가치가 커지고 있다. - Figma에서는 다양한 직군이 글쓰기를 업무의 일부로 활용한다. - 엔지니어: 새로운 기술적 접근을 설명하는 문서 작성 - 디자이너: 디자인 결정의 근거와 의도 발표 - 제품 관리자: 팀의 목표를 정렬하는 PRD 작성 - Microsoft와 Slack 같은 기업도 글쓰기를 깊이 있는 사고와 명확한 커뮤니케이션, 아이디어에 대한 동의 확보를 위한 방법으로 활용해 왔다. - 사람들이 좋아하는 기능이나 제품의 이면에는 대개 다음을 설득력 있게 설명한 사람이 있다. - 왜 이 제품이나 기능이 필요한가 - 누구를 위한 것인가 - 사용자의 삶을 어떻게 개선하는가 ## 글쓰기는 정리된 사고다 - 빈 페이지와 깜빡이는 커서는 누구에게나 부담스러울 수 있다. - 하지만 생각할 수 있다면 쓸 수도 있다. 글쓰기는 머릿속 생각을 구조화하고 문제를 풀어가는 과정이기 때문이다. - 생각을 글로 옮기면 다음과 같은 효과가 있다. - 아이디어의 핵심을 명확히 파악할 수 있다. - 논리의 빈틈이나 모순을 발견할 수 있다. - 더 나은 결과와 결론에 도달할 수 있다. - 컴퓨터 과학자 레슬리 램포트의 말처럼, 쓰지 않고 생각할 때는 실제로 생각하고 있다고 착각하기 쉽다. ## 막힐 때 활용할 수 있는 방법 - 머릿속에서만 고민하고 있다면 다른 사람에게 말로 설명해 본다. - 자신의 설명을 녹음해 보면, 첫 번째 글보다 자연스러운 말투가 더 명확하게 느껴질 수 있다. - 글쓰기 능력을 키우려면 다양한 글을 읽는 것도 도움이 된다. - 책과 잡지 - 포장지나 일상적인 인쇄물 - 긴 온라인 글이나 Reddit 스레드 등 - 완벽한 첫 문장을 만들려 하기보다, 우선 생각을 밖으로 꺼내고 나중에 다듬는 접근이 효과적이다. 결국 스토리텔링은 작가나 발표자만의 기술이 아니다. 자신의 아이디어를 말로 설명하고, 이를 글로 정리한 뒤, 피드백과 반복적인 수정을 거치는 습관을 들이면 누구나 더 설득력 있는 커뮤니케이터가 될 수 있다.

technical-writingdesign-thinkingproduct-managementstorytelling+2