하나의 마크다운 원본으로 웹 위키와 Word 문서, 그리고 한글·영문까지 함께 관리하기
제품이 성장할수록 사용자 매뉴얼도 함께 커집니다.
새로운 기능이 추가되고 화면이 바뀔 때마다 Word 문서를 수정하고, 고객사별 버전을 복사하고, 영문 매뉴얼까지 다시 손보는 작업은 생각보다 많은 시간을 소모합니다. 문제는 시간이 아니라 신뢰성입니다. 여러 사본 가운데 하나라도 수정이 누락되면 사용자는 실제 화면과 다른 매뉴얼을 보게 되고, 문서는 빠르게 신뢰를 잃습니다.
저희도 같은 문제를 겪었습니다.
그래서 더 이상 문서를 만드는 방식이 아니라 문서를 운영하는 방식을 바꾸기로 했습니다.
현재는 한국어 43개 챕터와 영문 43개 챕터, 총 86개의 가이드 문서를 하나의 Markdown 기반으로 운영하고 있으며, 같은 원본에서 솔루션에 탑재되는 위키 사이트와 배포용 Word 문서를 동시에 생성하고 있습니다.
이번 글에서는 왜 기존 문서 체계를 버리고 위키 기반으로 전환했는지, 그리고 운영하면서 얻은 경험을 공유합니다.
같은 내용을 여러 번 수정하는 구조가 가장 큰 문제였습니다
예전에는 화면 하나가 변경될 때마다 여러 문서를 수정해야 했습니다.
- 표준 사용자 가이드
- 고객사별 가이드
- 인증 심사용 문서
- 영문 매뉴얼
같은 내용을 여러 번 수정하는 일은 단순 반복처럼 보이지만, 실제 위험은 누락에서 발생합니다.
한 문서라도 수정하지 못하면 고객은 오래된 화면을 보게 되고, 지원 문의가 이어집니다.
"매뉴얼에는 있는데 실제 화면에는 없습니다."
이 한마디가 문서 전체의 신뢰도를 무너뜨립니다.
문서보다 먼저 바뀐 것은 '원본'이었습니다
많은 팀이 Word를 버리고 웹 문서를 도입했다고 이야기합니다.
하지만 저희가 바꾼 것은 출력 형식이 아니라 원본 관리 방식입니다.
핵심 원칙은 단 하나였습니다.
원본은 하나, 산출물은 여러 개.
현재는 Markdown 하나만 관리합니다.
그 원본으로부터 다음 산출물이 자동 생성됩니다.
- 솔루션에 탑재되는 가이드 위키
- 배포용 Word(docx)
- 한국어 문서
- 영문 문서
사용자는 웹에서 최신 가이드를 확인하고, 고객사가 문서 제출을 요구하면 같은 원본에서 Word를 생성합니다. 웹과 문서를 따로 관리하지 않기 때문에 내용이 달라질 가능성도 크게 줄었습니다.
한글과 영문도 같은 구조로 운영합니다
문서가 많아질수록 다국어 관리도 또 하나의 부담이 됩니다.
현재는 한국어 43개 챕터와 영문 43개 챕터를 동일한 정보 구조로 운영하고 있습니다.
각 챕터는 한국어와 영어가 1:1로 대응되며, 구조와 목차를 동일하게 유지합니다. 새로운 기능이 추가되면 동일한 위치에 한글과 영문 문서가 함께 생성되고 관리됩니다.
덕분에 언어마다 서로 다른 문서 체계를 유지할 필요가 없어졌고, 기능 추가나 메뉴 변경 시 번역 대상도 명확하게 관리할 수 있게 되었습니다.
고객사마다 다른 문서를 만들지 않습니다
또 하나의 고민은 고객사별 문서였습니다.
과거에는 고객사가 늘어날수록 문서도 함께 늘어났습니다.
하지만 지금은 고객사마다 별도의 매뉴얼을 만들지 않습니다.
대신 하나의 표준 원본 위에 Variant를 얹는 방식으로 운영합니다.
예를 들어
- Standard
- Customer J
- Certification
처럼 필요한 부분만 분기합니다.
공통 내용은 하나만 수정하면 모든 버전에 자동 반영되고, 고객사마다 다른 내용만 별도로 관리합니다.
덕분에 문서 수는 늘어나지 않으면서 고객별 요구사항은 그대로 대응할 수 있게 되었습니다.
가장 크게 달라진 것은 '라이브 화면'이 기준이 되었다는 점입니다
문서를 운영하면서 얻은 가장 큰 교훈은 하나였습니다.
정답은 코드가 아니라 사용자가 보는 화면입니다.
개발 코드에는 기능이 존재하더라도 실제 화면에서 노출되지 않는다면 사용자에게는 없는 기능입니다.
그래서 문서 역시 코드가 아니라 라이브 화면을 기준으로 작성합니다.
이를 위해 화면 가용성을 자동으로 점검하고 그 결과를 screen-truth.json에 저장합니다.
각 화면이 실제 열리는지, 삭제되었는지, 접근 가능한지를 자동으로 확인하고, 더 이상 존재하지 않는 화면을 참조하는 메뉴와 링크는 문서에서도 함께 제거합니다.
이후부터는 "문서는 있는데 화면은 없는" 상황이 크게 줄었습니다.
자동화보다 더 중요한 것은 작성 규칙이었습니다
자동화가 모든 문제를 해결해 주지는 않았습니다.
초기에는 화면을 확인하기 전에 본문부터 작성하는 경우가 많았습니다.
하지만 실제 UI와 버튼명이 달라 문서를 다시 수정하는 일이 반복되었습니다.
결국 작업 순서를 바꿨습니다.
먼저 화면을 캡처하고, 그다음 문서를 작성합니다.
또 하나의 교훈은 자동화가 늘어날수록 가이드가 더 중요해진다는 점입니다.
현재는
- 무엇을 작성해야 하는지(사실 규칙)
- 어떻게 작성해야 하는지(문체 규칙)
를 별도의 문서로 관리합니다.
원본이 하나일수록 작은 실수가 모든 산출물로 확산될 수 있기 때문입니다.
실제로 가장 크게 달라진 점
운영하면서 체감한 변화는 생각보다 단순했습니다.
첫째, 제품이 변경되면 원본 한 곳만 수정하면 끝납니다. 웹 위키와 Word, 고객사 Variant, 한글과 영문 문서까지 모두 같은 원본에서 생성됩니다.
둘째, 문서를 찾는 방식이 달라졌습니다. Word에서 페이지를 찾는 대신 URL 하나로 원하는 내용을 바로 공유할 수 있습니다.
셋째, 문서의 최신성이 유지됩니다. 라이브 화면을 기준으로 검증하기 때문에 제품보다 문서가 뒤처지는 시간이 크게 줄었습니다.
이런 팀이라면 위키 기반 전환을 추천합니다
위키가 모든 팀에 정답은 아닙니다.
하지만 다음과 같은 환경이라면 효과를 체감할 가능성이 높습니다.
- 제품이 자주 업데이트된다
- 고객사별 문서를 여러 버전 운영한다
- 한국어와 영문 문서를 함께 관리한다
- 웹 가이드와 Word 문서를 동시에 제공해야 한다
- 매뉴얼이 수십 개 이상의 챕터로 구성되어 있다
저희 역시 문서가 늘어나기 전에는 Word만으로도 충분했습니다.
하지만 챕터 수가 수십 개를 넘어가고 고객사별 버전과 다국어 문서까지 함께 관리하기 시작하면서, 문서를 만드는 방식보다 운영하는 방식이 더 중요하다는 사실을 체감했습니다.
지금은 하나의 Markdown 원본을 중심으로 웹 위키, Word, 한국어·영문 문서, 고객사별 Variant까지 모두 같은 흐름으로 관리하고 있습니다.
결국 위키를 선택한 이유는 새로운 도구를 쓰기 위해서가 아니라, 문서를 제품처럼 지속적으로 운영하기 위해서였습니다.