Vale을 사용하여 문서 편집 프로세스를 개선 (새 탭에서 열림)
데이터독(Datadog)은 대규모 오픈 소스 기여자와 수많은 제품군을 보유한 환경에서 문서의 일관성과 품질을 유지하기 위해 'Vale'이라는 오픈 소스 산문 린터(Linter)를 도입했습니다. 이를 통해 수동 편집에 드는 리소스를 대폭 줄이고, 스타일 가이드를 코드로 관리함으로써 문서 검토 과정을 자동화하는 성과를 거두었습니다. 결과적으로 작성자가 코드를 제출하기 전 단계에서부터 스스로 문서를 수정할 수 있는 '시프트 레프트(Shift-left)' 문화를 정착시켜 전체적인 문서화 효율을 높였습니다. ### 대규모 문서 기여 관리의 한계 * 데이터독 문서팀은 약 14명의 작가가 1,400명 이상의 기여자(내부 개발자 및 외부 기여자)가 생성하는 문서를 관리하며, 작가 1인당 개발자 비율은 200대 1에 달합니다. * 2023년 한 해에만 35개 이상의 제품과 수백 개의 API, 통합 서비스에 대해 20,000개 이상의 풀 리퀘스트(PR)를 처리했습니다. * 당번 작가는 하루 평균 40개 이상의 PR을 검토해야 하므로, 수동으로 모든 문법, 어조, 스타일 가이드를 확인하는 것은 물리적으로 불가능한 상황이었습니다. ### Vale를 활용한 문서 스타일 린팅 자동화 * 오픈 소스 CLI 도구인 Vale를 작성 환경과 CI(지속적 통합) 워크플로우에 통합했습니다. * GitHub Actions를 통해 PR이 생성될 때마다 Vale이 HTML 및 마크다운 파일을 스캔하여 스타일 규칙 위반 사항을 자동으로 댓글로 남깁니다. * 너무 긴 문장, 불필요한 수식어 사용, 오래된 타자기 습관(이중 공백 등)을 자동으로 감지하여 작가가 검토하기 전에 기여자가 스스로 수정할 수 있게 합니다. ### 스타일 가이드의 코드화 (Codifying Style Guide) * 과거에는 컨플루언스(Confluence)나 위키 등에 흩어져 있던 편집 가이드라인을 `datadog-vale`이라는 오픈 소스 프로젝트를 통해 코드 형태로 변환했습니다. * YAML 형식을 사용하여 검증하고자 하는 스타일 규칙을 정의하며, 정규 표현식(RegEx)을 통해 특정 패턴(예: 옥스퍼드 콤마 누락)을 감지합니다. * 특정 단어(simply, easily 등)를 지양하게 하는 `words.yml`, 라틴어 약어 대신 쉬운 영어를 쓰게 하는 `abbreviations.yml` 등의 규칙을 통해 일관된 어조를 유지합니다. * 휴고(Hugo) 숏코드와 같이 스타일 검사에서 제외해야 할 영역은 정규 표현식으로 필터링하여 오탐지를 방지합니다. ### 실용적인 제언 대규모 팀이나 프로젝트를 운영하고 있다면 스타일 가이드를 단순히 문서로만 남기지 말고, Vale와 같은 도구를 사용해 자동화된 규칙으로 변환하는 것이 좋습니다. 데이터독이 공개한 `datadog-vale` 규칙을 참고하면 옥스퍼드 콤마 사용이나 전문 용어 관리 등을 손쉽게 자신의 프로젝트에 적용해 볼 수 있습니다.