knowledge-management

6 개의 포스트

toss

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

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

toss

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

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

toss

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

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

toss

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

토스의 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의 전문성은 글쓰기 자체뿐 아니라 지식을 발견하고, 구조화하고, 전달하며, 자동화하는 능력으로 넓어지고 있습니다. 조직의 지식을 개인의 기억이나 메신저 기록에만 남겨두지 않으려면 코드와 맥락을 함께 관리해야 합니다. 문서를 단순한 참고 자료가 아니라 업무 흐름 속에서 바로 활용되는 시스템으로 설계하고, 반복적인 작성과 관리를 자동화하는 방향이 실용적인 접근입니다.

toss

전문성 밖으로 나아가기 (새 탭에서 열림)

Technical Writer(TW)는 문서를 작성·관리하는 역할을 넘어, 지식이 축적되고 활용되는 제품과 시스템을 만드는 제품 오너로 확장되고 있다. 토스의 문서 플랫폼 ‘토독’은 누구나 쉽게 문서를 작성하고, 조직의 지식을 한곳에 모으며, AI가 활용할 수 있도록 하는 것을 목표로 한다. 궁극적으로는 문서화가 별도 업무가 아니라 실제 업무 과정에서 자동으로 발생하고, 지식의 최신성과 품질까지 시스템이 관리하는 구조를 지향한다. ## TW가 제품을 만드는 이유 - TW는 어떤 문서가 읽기 어려운지, 좋은 문서의 조건이 무엇인지, AI가 잘 활용할 수 있는 문서 구조가 무엇인지 깊이 고민해 온 직무다. - 이러한 전문성을 문서 작성에만 적용하지 않고, 문서와 지식 관리 제품의 설계 원칙으로 확장한다. - 제품 오너로서 사용자 인터뷰, 제품 방향 설정, 로드맵·우선순위 결정, 기능 기획과 구현까지 직접 수행한다. - 문서 요구사항을 개발팀에 전달하는 역할이 아니라, 제품의 문제를 정의하고 해결책을 만드는 메이커로 일한다. ## 기존 내부 문서의 문제점 - **높은 작성 장벽** - 정적 사이트 생성기 기반 문서는 저장소 클론, 마크다운 작성, PR 생성과 리뷰 과정을 거쳐야 했다. - 개발자에게는 익숙하지만 디자이너나 PM에게는 문서 작성 자체를 포기하게 만드는 장벽이 됐다. - **낡고 불필요한 지식의 누적** - 작성자와 작성 이유를 알 수 없는 메모, 변경된 정책을 설명하는 문서, 미완성 초안 등이 쌓였다. - 문서의 양이 많아질수록 실제로 신뢰할 수 있는 지식을 판별하기 어려워졌다. - **지식의 파편화** - 문서가 SSG, 문서 도구, 코드, 메신저 대화, 개인의 기억 등에 흩어져 있었다. - 지식이 한곳에 모이지 않으면 조직 차원의 축적과 재활용이 어려웠다. ## 토독의 핵심 가치 - **누구나 쉽게 문서 작성** - 별도의 개발 과정 없이 문서를 만들고 수정할 수 있다. - GitHub, 기존 문서 도구, 사내 메신저 등 다양한 출발점의 지식을 토독으로 연결할 수 있다. - **AI를 통한 지식 활용** - 토독의 문서를 팀별 봇과 연결할 수 있다. - API, CLI, MCP를 제공해 요청 봇, 제품 스펙 관리 등 다양한 방식으로 활용할 수 있다. - **단일 진실 공급원(SSoT)** - 여러 곳에 흩어진 정보를 모아 완결된 문서로 구성한다. - 어떤 지식이 최신이고 유효한지 한곳에서 확인할 수 있게 한다. - **확장 가능한 플랫폼** - 조직이나 팀마다 별도 도구를 선택하고 인프라를 구축할 필요가 없다. - 하나의 플랫폼 안에서 각 팀이 독립적인 문서 공간을 운영할 수 있으며, 계열사로도 확장할 수 있다. ## 문서 품질을 자동으로 관리하기 - 문서 작성 장벽을 낮추면 문서 수는 늘지만 품질이 떨어질 수 있다. - 기존에는 TW가 직접 문서를 리뷰하고 낡은 문서를 찾아 수정했다. - 토독은 TW가 정의한 ‘좋은 문서’의 기준을 다음 기능으로 전환하고 있다. - AI 교정 기능 - 문서 봇을 통한 초안 작성 - 자동 리뷰와 개선점 제안 - 다만 사용자가 직접 문서를 작성해야 한다는 전제만으로는 충분하지 않다고 판단했다. ## 업무 과정에서 자동으로 생성되는 문서 - 문서화를 별도의 업무로 요구하기보다, 일하는 과정에서 자연스럽게 문서가 생성되도록 한다. - 사내 메신저의 의사결정과 논의, 코드 변경 내역 등을 자동으로 문서화한다. - 코드 변경이나 의사결정 이후의 논의를 모니터링해 문서가 계속 갱신되도록 설계한다. - 단순히 정보를 수집하는 데 그치지 않고 다음을 판단하는 것이 목표다. - 정책과 실제 코드가 일치하는가 - 해당 지식이 실제 업무에서 사용되고 있는가 - 문서가 얼마나 최신 상태인가 - 현재도 유효한 지식인가 ## TW 전문성의 시스템화 - 좋은 문서를 직접 쓰는 능력에서, 좋은 문서가 반복해서 생산되도록 시스템을 설계하는 능력으로 중심이 이동한다. - 문서가 읽히지 않는 이유에 대한 경험은 누구나 쉽게 쓰고 AI도 잘 읽는 문서 기준으로 전환된다. - 좋은 문서에 대한 판단은 AI 교정과 자동 리뷰의 기준이 된다. - 낡은 문서를 식별하고 유효성을 판단하는 역량은 지식 신선도와 신뢰도를 관리하는 시스템으로 구현된다. - TW의 역할은 다음과 같이 정리된다. - 흩어진 지식이 모일 장소를 만든다. - 좋은 문서의 기준을 정의한다. - 사람의 판단을 시스템에 반영한다. - 업무 과정에서 문서가 자연스럽게 만들어지게 한다. - 축적된 지식이 스스로 갱신되도록 한다. ## 지향하는 업무 환경 - 시스템이 오래된 문서를 감지해 담당자에게 알리고 개선안을 제안한다. - 프로젝트 관리 도구를 별도로 갱신하지 않아도 업무 과정의 기록이 자동으로 정리된다. - 릴리즈 공지와 반복적인 문의 답변이 지식으로 남아 신규 구성원의 학습 비용을 줄인다. - 한 번의 업무가 조직 전체에서 재사용 가능한 흔적으로 남아 실행 시간을 단축한다. - TW는 반복적인 문서 관리보다 제품의 방향과 지식 거버넌스 설계에 집중한다. 결국 토독의 목표는 문서를 잘 쓰게 만드는 데서 끝나지 않는다. 조직의 업무 흐름 자체가 신뢰할 수 있는 지식을 만들고 갱신하도록 설계하는 것이 핵심이며, 이는 TW의 전문성을 조직 전체의 시스템으로 확장하는 방식이다.

line

ODW #8: Slack MCP로 사고 대응과 FAQ 생성 작업 속도를 높이는 실습형 사내 워크숍 후기 (새 탭에서 열림)

Slack에 축적된 문의와 사고 대응 정보는 중요하지만, 문서화가 늦어지거나 담당자별 품질 차이로 지식 자산화가 어려웠다. 이 글은 사내 인증 기반 Slack MCP와 Confluence·Jira MCP를 결합해 FAQ, 사고 상황 요약, 인시던트 리포트를 자동 생성하는 워크숍 사례를 소개한다. 핵심은 기술 설명보다 실제 업무를 직접 자동화해 보고, 검증된 프롬프트를 스킬로 만들어 조직 전체에서 재사용하는 데 있다. ## Slack 정보의 구조화 격차 - Slack에는 사고 대응, 문의, 프로젝트 논의 등 실시간 업무 정보가 축적된다. - 그러나 문서화가 본업에 밀리거나 담당자에 따라 기록 품질이 달라진다. - 그 결과 중요한 정보가 Slack 스레드에 묻혀 재검색과 재활용이 어려워진다. - FAQ, 사고 보고서, 진행 상황 보고서 형태로 Confluence나 Jira에 정리할 필요가 있다. ## Slack MCP 도입과 워크숍 목표 - 사내 Slack MCP는 사내 인증과 연동되어 개인 토큰이나 복잡한 OAuth 설정 없이 Slack 정보에 접근할 수 있다. - 새로운 도구의 도입을 막는 요인은 다음과 같다. - 업무 중 별도로 학습할 시간 부족 - 설정과 활용에 대한 심리적 부담 - 사내 정보 확산의 지연 - 워크숍은 Slack MCP가 공개된 직후 빠르게 열어 참가자의 관심을 실습으로 연결했다. - 목표는 깊은 기술 지식 전달보다 참가자가 당일부터 업무에 활용할 수 있게 만드는 것이었다. ## Slack MCP의 주요 기능과 확장성 - Slack MCP는 다음 기능을 제공한다. - 메시지와 스레드 조회 - 메시지 게시 및 액션 실행 - 채널과 멤버 조회 - 메시지 검색 - Confluence MCP와 결합하면 프로젝트 보고서나 FAQ를 자동 생성하고 게시할 수 있다. - Jira MCP와 결합하면 Slack 논의를 바탕으로 작업 티켓을 만들 수 있다. - 워크숍에서는 먼저 AI에게 Slack 채널에 “Hello”를 게시하게 하여 MCP의 동작을 직접 체험하게 했다. ## 문의 대응 내용을 FAQ로 변환 - Slack 문의 채널의 대화를 검색해 FAQ 형식의 마크다운으로 변환했다. - 기존 Confluence FAQ와 대조해 이미 문서화된 내용은 제외했다. - 생성된 내용을 Confluence 하위 페이지로 게시하고, 증상·해결책·원인 구조의 표로 정리했다. - 활용 흐름은 다음과 같다. - 문의 채널과 Confluence 페이지 지정 - ‘문의’를 포함한 최신 스레드 검색 - 기존 FAQ와 중복 여부 확인 - 신규 문의만 FAQ 파일로 생성 - Confluence에 게시 - 이를 통해 반복 문의를 지식 베이스로 축적하고 담당자별 답변 품질 차이를 줄일 수 있다. ## 사고 상황 요약과 인시던트 리포트 생성 ### 빠른 상황 파악 - “시스템 장애 내용 및 상황을 정리해줘”와 같은 자연어 지시로 Slack 스레드를 검색한다. - AI는 해결 상태, 고객 영향, 담당자별 조치, 장애 타임라인을 요약한다. - 예를 들어 장애 감지 시각, 원인 파악 시각, 대응 완료 시각을 한눈에 정리할 수 있다. - 매니저가 중간에 합류하거나 담당자에게 직접 묻기 전에 전체 상황을 파악할 수 있어 의사 결정이 빨라진다. ### 인시던트 리포트 자동 작성 - 사전에 정한 형식에 따라 발생 시각, 감지 시각, 장애 기간, 원인, 영향 범위, 대응 내용을 자동 구조화한다. - 데이터베이스 커넥션 풀 고갈이나 설정 변경 누락 같은 원인과 사용자 수, 영향 기능, 데이터 손실 여부 등을 보고서에 포함할 수 있다. - 사고 대응 중에는 현황 요약을, 대응 완료 후에는 공식 리포트를 생성하는 식으로 목적에 맞게 활용한다. ## 정확도와 리뷰를 높이는 방법 - Slack의 모든 정보를 그대로 사용하지 말고 분석 범위를 먼저 좁혀야 한다. - 기존 Confluence 문서와 중복 제거 - 특정 리액션이 달린 메시지만 선택 - 특정 채널이나 기간, 키워드로 검색 범위 제한 - AI가 생성한 결과를 그대로 공개해서는 안 된다. - 개인정보 포함 여부 확인 - 원본 스레드 출처 표시 - 원래 발언을 과도하게 해석하지 않았는지 검토 - 실제 실습에서도 원본 스레드의 의도와 FAQ 내용이 미묘하게 달라지는 사례가 있어 사람의 리뷰가 필요함을 확인했다. - “증상·해결책·원인 세 칼럼의 표로 작성”처럼 출력 형식을 구체적으로 지정하면 팀 문서 표준에 맞는 결과를 얻기 쉽다. ## 재사용 가능한 스킬 설계 - 반복 작업은 스킬로 저장해 프롬프트를 매번 다시 작성하지 않도록 했다. - 워크숍에서 사용한 스킬은 다음 네 가지다. - `slack-to-faq`: Slack 스레드에서 FAQ 생성 - `faq-to-confluence`: FAQ를 Confluence에 게시 - `slack-incident-status`: 사고 상황 요약 - `slack-incident-report`: 인시던트 리포트 생성 - 스킬 제작 과정은 다음과 같다. - 수동으로 여러 프롬프트를 실험 - 효과적인 지시와 출력 형식 기록 - 재사용 가능한 스킬로 정의 - 팀에 공유하고 피드백을 반영해 개선 - 이를 통해 워크숍 참가자가 같은 절차를 재현하고, 팀 전체가 일관된 품질의 결과를 얻을 수 있다. ## 워크숍 운영에서 얻은 교훈 - 신기술이 등장해 관심이 높은 시점에 빠르게 교육을 제공하면 학습 참여를 높일 수 있다. - “Hello” 게시처럼 단순한 성공 경험부터 시작한 뒤 FAQ 생성과 사고 대응으로 난도를 높이는 단계적 구성이 효과적이다. - 일반적인 기능 소개보다 문의 대응과 장애 대응처럼 실제로 시간이 많이 드는 업무를 주제로 삼아야 활용 가능성을 쉽게 체감할 수 있다. - 기술 자체보다 참가자가 직접 손을 움직여 자신의 업무에 적용해 보는 경험이 현장 정착에 중요하다. 실무에서는 Slack MCP를 전사적으로 한꺼번에 도입하기보다, 반복 문의나 인시던트 보고처럼 효과를 측정하기 쉬운 업무부터 시작하는 것이 좋다. 원본 출처와 사람의 검토 절차를 반드시 포함하고, 검증된 작업 흐름은 스킬로 표준화해 점진적으로 확산하는 방식이 적절하다.