이번 발표자 Manny Silva는 지난 4월 이번 발표와 같은 제목으로 책을 펴냈습니다. 아마 자세한 내용은 책을 보시면 나와 있을 것 같네요.
Docs as Tests: A Strategy for Resilient Technical Documentation
https://www.amazon.com/Docs-Tests-Resilient-Technical-Documentation-ebook/dp/B0F1H97QSL
1. 문제 인식: 문서와 제품의 불일치
제품 UI, API, 코드 등이 변경될 때 문서는 자주 뒤처져 사용자 혼란과 신뢰 저하, 지원 비용 증가, 심지어 법적 문제까지 발생할 수 있음.
전통적 문서 검증은 수동 테스트에 의존해 한계가 많음. 실제로는 사용자들이 문서를 사용하며 오류를 발견하는 경우가 많음.
물론 안정적인 문서화 프로세스를 가지고 있는 경우 제품 개발 프로세스 내 문서 작업이 포함되어 있어 문서화를 거쳐야 배포가 되도록 정리하고 있습니다. 하지만 그럼에도 놓칠 수 있는 부분이 있고(개발자가 이건 문서화 대상이 아니라고 판단하는 경우 등) 그렇기 때문에 문서에 대한 테스트가 중요할 수 있습니다.
2. Docs as Tests 전략의 핵심
Docs as Tests는 문서의 각 단계, 예시, 스크린샷, 코드 블록 등을 ‘테스트 가능한 주장(assertion)’으로 간주해 자동화된 검증을 도입하는 전략임.
문서와 제품이 항상 일치하는지 반복적으로 자동 테스트를 돌려 신뢰성과 정확성을 유지함.
이 전략은 lint, 스타일 체크, 링크 체크와는 다르며, 실제 제품 동작과 문서의 일치 여부를 검증하는 데 초점을 둠.
Docs as Tests에 대해 아래와 같이 6가지로 정의하고 있습니다.
- 문서와 제품 간의 UX 검증
- 자동화된 최신성 테스트
- 문서와 제품 간의 제로 트러스트(Zero-trust) 관계
- 테스트 가능한 명제로서의 절차
- 엔드 투 엔드(End-to-end) 테스트로서의 문서
- 사용자 신뢰를 구축하고 유지하는 방법
3. 적용 방법
UI 문서는 Playwright, Cypress 등으로 실제 클릭, 폼 제출, 내비게이션 경로 등을 자동화 테스트.
API 문서는 OpenAPI, Postman, Bruno 등으로 실제 요청/응답, 워크플로우, 예시 코드의 동작 여부를 자동 검증.
코드 블록, 커맨드 라인 예제 등도 실제 실행해 결과를 검증.
일부 도구(예: Doc Detective)는 마크다운 내에 테스트 명령을 직접 포함해 문서와 테스트를 통합할 수 있음.
4. 단계적 도입과 조직 내 설득
처음부터 전체 문서에 적용하기보다는, 작은 단위의 절차나 중요 문서부터 시범 도입(‘cupcake부터 시작’)을 권장.
파일럿 성공 후, 조직 내 이해관계자(리더십, 엔지니어 등)에게 지원 요청.
지속적으로 테스트 범위를 확대해 나가며, CI/CD 파이프라인 등에도 통합 가능.
5. 주의사항 및 실무 팁
자동 테스트는 실제 데이터가 아닌 테스트 계정/환경에서 실행해야 하며, 생성된 리소스는 반드시 정리해야 함.
100% 테스트 커버리지를 목표로 하기보다는, 점진적 확대와 실용성을 중시.
다양한 도구가 있으니 팀의 기술 역량과 상황에 맞는 도구를 선택할 것.
결론
‘Docs as Tests’는 문서를 제품과 동기화하고, 사용자 신뢰를 높이며, 조직의 지원 비용을 줄일 수 있는 실질적 전략임.
자동화 도구와 단계적 접근을 통해 누구나 시작할 수 있으며, 문서팀의 업무 효율과 문서 품질을 동시에 높일 수 있음.
7 Docs As Tests- Manny Silva
www.flickr.com
https://youtu.be/3Q1WtyhO_sQ?si=qBra8dqDjwFADFOJ
