멀티플랫폼 문서 관리 효율화를 위한 싱글 소싱 적용 사례

싱글 소싱 개념 및 중요성

• 싱글 소싱은 단일 소스에서 다양한 포맷이나 맥락에 따라 여러 문서를 생성하는 기법입니다.
• 주요 목적은 '복사 및 붙여넣기' 작업을 최소화하여 문서 관리의 효율성을 높이고, 단일 출처에서 정보를 가져와 문서 품질의 일관성을 유지하는 것입니다.
• 조건부 콘텐츠(conditional content), 변수 처리(variables), 콘텐츠 재사용(content reuse) 등의 기법을 활용하여 구현합니다.
• 공통된 부분이 많지만 차이가 있는 제품군이나 소프트웨어 배포 환경에 따라 문서를 만들 때 유용합니다.

LINE Planet Docs 아키텍처 및 싱글 소싱 설계

• LINE Planet은 음성/영상 통화 기능을 제공하는 VoIP 플랫폼으로, iOS, Android, macOS, Windows, 웹, Flutter 등 다양한 플랫폼 SDK를 지원합니다.
• Planet Docs는 이러한 SDK 문서를 버전 관리하고, 한국어, 영어, 일본어 다국어화를 지원하며, 플랫폼별 기능/구현 방식의 차이를 반영해야 합니다.
• 문서화 도구로는 Docusaurus를 활용하여 멀티 인스턴스, 버전 관리, 마크다운 임포트 기능을 통해 복잡한 요구사항을 충족합니다.
• 싱글 소싱은 React 컴포넌트 개발, API 메타데이터(YAML) 준비, 조건부 콘텐츠 및 변수 처리용 컴포넌트를 사용한 공유 문서 작성, 플레이스홀더 문서 생성, 빌드 과정을 통해 플랫폼별 실제 문서를 생성하도록 설계되었습니다.

싱글 소싱 구현 상세 및 확장

• 조건부 콘텐츠는 <Conditional> 컴포넌트를 통해 특정 인스턴스(android, iosmacos, windows, web)에 따라 내용을 필터링합니다.
• 변수 처리는 <Api> 컴포넌트와 인스턴스 및 버전별 API 메타데이터를 사용하여, 공유 문서 내 변수 부분을 플랫폼별 실제 API 이름으로 대체합니다.
• 콘텐츠 재사용은 Docusaurus의 마크다운 임포트 기능을 활용하여 페이지 단위의 공유 문서를 플랫폼별 문서에서 가져와 사용합니다.
• 기능 확장으로 API 포함 관계 표현을 위해 2수준 메타데이터 구조와 showParent 속성을 도입했으며, API 레퍼런스 링크 제공을 위해 메타데이터에 path 필드를 추가하고 withLink 속성으로 제어합니다.

적용 효과 및 고려사항

• 전제 조건으로 API 설계 및 네이밍의 균일성이 요구되며, 이는 싱글 소싱의 핵심인 API 메타데이터 변수 처리를 가능하게 합니다.
• 제약 사항으로는 튜토리얼과 같이 구현 단계에 가까워질수록 플랫폼별 차이가 커져 모든 유형의 문서에 싱글 소싱을 적용하기 어렵습니다.
• 주요 효과는 문서 관리 효율성 개선, 문서 품질 향상, 플랫폼 간 차이점 추적 용이성, 다국어화 비용 및 공수 절감 등입니다.
• 싱글 소싱 문서 작성 및 유지보수에는 프로덕트의 API 구조에 대한 테크니컬 라이터의 깊은 이해와 개발 팀의 문서 구조 인지가 필요합니다.