Vale를 사용하여 문서 편집 프로세스를 개선하는 방법 (새 탭에서 열림)
데이터독(Datadog) 문서화 팀은 수많은 기여자 사이에서 일관된 문서 품질을 유지하기 위해 오픈 소스 산문 린터(Prose Linter)인 'Vale'을 도입하여 스타일 가이드 적용을 자동화했습니다. 개발자들이 코드 린터를 사용하듯 문서에도 자동화된 검사 도구를 통합함으로써, 1,400명이 넘는 기여자가 생성하는 방대한 양의 문서를 효율적으로 관리하고 기술 작가의 리뷰 부담을 획기적으로 줄였습니다. 결과적으로 이 시스템은 고품질의 문서를 더 빠르게 배포할 수 있는 '시프트 레프트(Shift-left)' 전략을 실현했습니다. **대규모 문서 관리의 한계와 자동화의 필요성** * 데이터독은 약 1,400명의 내부 및 외부 기여자가 생성하는 35개 이상의 제품 문서를 관리하며, 연간 20,000개 이상의 풀 리퀘스트(PR)를 처리합니다. * 기술 작가 한 명당 개발자 비율이 1:200에 달하는 상황에서, 모든 문서의 문법, 전문 용어, 시제, 성별 중립적 언어 등을 수동으로 검토하는 것은 불가능에 가깝습니다. * LLM(대형 언어 모델)을 사용하더라도 데이터독 특유의 스타일 가이드(예: 옥스퍼드 콤마 사용, 'currently' 같은 시간 표현 지양 등)를 완벽히 준수하기 어렵기 때문에 자동화된 검증 도구가 필수적입니다. **Vale를 활용한 문서 스타일 린팅** * 오픈 소스 도구인 Vale를 GitHub Actions와 통합하여 CI(지속적 통합) 워크플로우 내에서 문서 스타일을 자동으로 검사합니다. * 기여자가 PR을 생성하면 Vale가 `vale.ini` 설정 파일을 바탕으로 HTML 및 마크다운 파일을 스캔하고, 수정이 필요한 부분에 직접 자동 댓글을 남깁니다. * 이를 통해 기여자는 기술 작가가 리뷰를 시작하기 전에 스스로 문장을 수정할 수 있으며, 작가들은 반복적인 스타일 수정 작업에서 벗어나 콘텐츠의 기술적 정확성에 더 집중할 수 있습니다. **스타일 가이드의 코드화와 규칙 적용** * 기존에 Confluence나 위키에 흩어져 있던 복잡한 편집 지침을 YAML 형식의 린트 규칙으로 변환하여 관리합니다. * **불필요한 단어 제거**: `words.yml` 규칙을 통해 'easily', 'simply'와 같이 객관성이 떨어지는 수식어나 불필요한 전문 용어를 감지하여 경고를 보냅니다. * **구두점 및 문법 강제**: `oxfordcomma.yml`과 같은 규칙에 정규 표현식(Regex)을 사용하여 나열된 항목들 사이에 옥스퍼드 콤마가 누락된 경우를 찾아냅니다. * **약어 대체**: 라틴어 약어(e.g., i.e. 등)를 쉬운 영어 표현(for example, that is 등)으로 대체하도록 유도하는 `abbreviations.yml` 규칙을 적용하여 가독성을 높입니다. **실용적인 제언** 규모가 커지는 조직에서 문서의 일관성을 유지하고 싶다면, 스타일 가이드를 단순한 문서로 남겨두지 말고 Vale와 같은 도구를 통해 '코드로서의 문서(Docs-as-code)' 환경에 통합하는 것이 좋습니다. 처음에는 옥스퍼드 콤마나 금지어 목록 같은 간단한 규칙부터 시작하여 점진적으로 자동화 범위를 넓히면 리뷰 효율을 극대화할 수 있습니다.