WTD 베를린 2025 - 템플릿 문서 기반 자동화 테스트

조직의 규모가 커지고 제품의 범위가 넓어지면서 사용자 입장에서 딱 원하는 답을 찾기가 점점 어려워졌습니다. 그래서 기존 문서의 문제점을 분석하고 다른 조직의 문서를 검토하면서 How-to 형식의 문서와 튜토리얼 형식의 문서를 통합한 형식을 결정했습니다.

사용자가 원하는 문제를 찾아서 문서에 도달했을 때 아래와 같은 정보를 얻을 수 있습니다.

- Prerequisites (바닥부터 문제를 해결해 나갑니다)

- Copy/Paste steps (모든 코드는 복사해 바로 적용할 수 있습니다)

- Trouble Shooting (트러블슈팅이나 FAQ 정보를 분리하지 않고 같은 페이지 내에서 확인할 수 있습니다)

이와 같은 형식으로 템플릿을 만들고 개발자 그룹에서 템플릿을 채우는 형식으로 검증 과정을 진행했습니다. 문서를 작성하고 문서가 실제로 동작하는지 확인하는 것입니다.

문서 제목을 정할 때 일반적으로 영어의 경우 How-to 문서에서는 ~ing 형태를 많이 사용하는데, 그렇게 하면 사용자들이 검색할 때 입력하는 키워드와 일치하는 비율이 떨어진다고 합니다. 그래서 실제 사용자가 사용하는 언어를 기반으로 제목을 정했다고 하네요.

각 문서 상단에 TL;DR 항목을 추가해서 초보 개발자나 고급 개발자 모두에게 문서의 내용이 어떤 식으로 도움이 되는지 확인할 수 있게 합니다.

Prerequisites의 원칙은 사용자가 아무것도 설치하지 않았다는 것부터 시작합니다. 서드파티 제품도 마찬가지입니다(이 부분은 매번 반복되는 내용이 있을 수 있는데 어떻게 했는지 궁금하네요).

아마도 반복되는 내용은 하나의 문서로 표시되지만 별도로 작성하고 가져오는 방식을 취하지 않았을까 합니다. 실제 Prerequisites 항목은 접힌 상태로 표시되어 필요한 경우에만 열어서 확인할 수 있게 하고 있습니다.
https://developer.konghq.com/how-to/configure-hashicorp-vault-as-a-vault-backend/

Validate 항목은 사용자가 제대로 따라왔는지 확인하는 용도로도 사용하지만, 문서 자동화 테스트를 위한 목적도 가지고 있습니다.

자동화된 테스트 방식은 자체 개발한 도구를 사용합니다. 도구에서 문서 페이지를 불러와서 각 코드 조각을 텍스트 형식으로 추출합니다. 그리고 이를 실행하는 거죠. 이렇게 하면 실제 사용자가 문서를 보면서 경험하는 것과 같은 방식으로 문서를 테스트할 수 있습니다(템플릿 형식으로 문서를 만들기 때문에 가능한 방식이네요).