피드로 돌아가기
Dev.toDevOps
원문 읽기
Single Source 기반 README 동기화로 다국어 문서 Drift 완전 제거
How I stopped my README.md and README.zh.md from drifting apart
AI 요약
Context
다국어 README 유지보수 시 원본과 번역본 간의 내용 불일치(Drift) 발생 및 추적 불가한 구조적 한계 존재. 수동 동기화 방식의 낮은 신뢰도로 인한 문서 품질 저하와 리뷰어의 검증 비용 증가 문제 직면.
Technical Solution
- Single Source of Truth 원칙을 적용한 README.src.md 템플릿 기반의 N-Output 생성 구조 설계
- Shared, Language-tagged, Inline-phrase의 세 가지 텍스트 처리 계층을 통한 내용 분리 및 재사용성 확보
- GitHub Action을 활용한 CI drift-check 메커니즘 도입으로 커밋된 파일과 생성 파일 간의 Diff 검증 강제
- 단순 텍스트 치환을 넘어 TOC, FileTree, Shell Output 등을 처리하는 Widget 인터페이스 기반 확장 구조 구현
- Java-based Core 로직을 CLI, Maven Plugin, GitHub Action 등 다양한 인터페이스로 캡슐화하여 통합 환경 제공
실천 포인트
- 다국어 문서 관리 시 Single Source of Truth 기반의 자동 생성 파이프라인 검토 - 단순 생성(Generation)을 넘어 CI 단계에서 실제 파일과의 일치 여부를 검증하는 Drift-check 도입 - 반복되는 문서 패턴을 Widget화하여 템플릿의 복잡도를 낮추고 일관성 유지 - 생성된 파일에 Header Comment를 삽입하여 수동 수정 방지 및 관리 주체 명시