개인적인 정리
Ben Perlmutter는 MongoDB Realm 문서 팀에서 일하고 있다고 합니다. Realm(렘)은 데이터 동기화 기술을 가진 기업으로 2019년 MongoDB에서 인수했더군요. 2017년부터 MongoDB에서 일을 시작했습니다.
간단하게 Realm이라는 것이 뭔지 설명해주며 시작합니다. 모바일 기기에 데이터를 저장했다가 서버와 동기화해주는 거라고 하네요. 요즘은 거의 모든 기기가 네트워크에 연결된 상태라 그럴 필요가 있나 싶지만 뭐 환경에 따라 그럴 수 있으니. 사이트 설명을 보면 SQLite을 대체하는 솔루션이라고 하네요.
문서 내에 포함하는 코드는 주로 사용자가 해당 코드를 복사해서 바로 사용하거나 약간의 수정 후 사용할 수 있게 구성되어 있습니다. 때문에 정상적으로 동작하는 것이 매우 중요합니다. 그래서 코드가 유효한지 확인할 수 있게 단위 테스트가 필요하다는 주장입니다.
문서 내 코드의 단위 테스트 방법은 두 가지입니다.
첫 번째는 코드를 테스트하고 테스트가 성공한 코드를 문서에 복사해 붙여 넣는 겁니다(수정이 필요할 때).
이 방법은 수작업이고 관리하기도 어렵고 일부 문서에 업데이트가 누락될 수도 있습니다.
그래서 고안한 것이 두 번째 아이디어인 추출해서 변환하기입니다.
코드를 테스트하는 것은 같지만 코드 내에서 문서에 포함될 부분을 추출해서 별도의 파일로 만들고 이를 문서 내에서 참조 형식으로 가져오는 것이죠. 이렇게 하면 수정된 코드를 문서에 따라 복사해 붙여 넣지 않아도 자동으로 업데이트가 된다는 컨셉입니다.
* 하지만 코드가 업데이트되면 코드를 설명하는 내용도 수정이 필요할 수 있습니다. 때문에 여전히 수작업은 필요할 듯 합니다.
이를 위해 팀에서 만든 도구가 Bluehawk라는 도구입니다.
annotate를 사용해 추출하거나 제외할 대상을 지정하고 CLI에서 파일을 생성하는 방식입니다.
MongoDB의 테크니컬 라이터 Caleb Thompson와 엔지니어 Chris Bush가 처음 만들었고 이를 계속해서 업데이트하고 있다고 합니다.
https://mongodb-university.github.io/Bluehawk/
realm 팀에서는 8개의 SDK, 2067개의 코드 샘플을 관리하고 있다고 하네요.
https://github.com/mongodb/docs-realm
이 방식의 장점은 복사해서 붙여 넣기 방식의 단점을 모두 보완하는 것이고 단점은 아직 완전한 자동화는 아니라는 점입니다.
Q&A
단위 테스트가 소스 변경 사항을 체크할 수 있나요?
매개변수 누락 같은 사항을 체크할 수 있다.
(하지만 옵션으로 추가되는 매개변수는 체크할 수 없을 듯)
다른 팀에서도 bluehawk를 사용하고 있나?
지난주 금요일에 1.0을 출시했고 아직 우리 팀만 사용하고 있다.
문서마다 다른 변수 값을 사용할 수 있나?
replace 기능을 지원한다
https://mongodb-university.github.io/Bluehawk/reference/tags#replace
영상
현장 스케치
Ben Perlmutter - Unit Test the Docs: Why You Should Test Your Code Examples
Explore writethedocs' photos on Flickr. writethedocs has uploaded 2645 photos to Flickr.
www.flickr.com
