발표자가 현재 직장(이전 직장은 MongoDB)으로 2020년 옮긴 후 문서 상황은 이러했습니다. 모든 문서는 엔지니어가 작성한 문서였고(테크니컬 라이터가 없는 상황이라서) 문서 배포는 루비로 직접 구현한 도구를 사용하고 있었습니다. 해당 도구를 처음 개발한 개발자는 너무 바빠서 유지보수를 할 수 없었고 사내에 루비를 아는 다른 엔지니어는 없었습니다. MinIO(현재 직장)에서 다루는 제품은 상당히 복잡합니다. 이 말은 다양한 그룹의 사용자를 가지고 있다는 이야기이고, 하나의 문서로 모든 사용자 요구를 만족시키기 어렵다는 것입니다.
작은 규모의 스타트업에서 자체 개발한 문서 도구를 사용하는 것은 무리라고 판단해서 스핑크스(Sphinx)로 전환하기로 했습니다. 이전 직장(MongoDB)에서 사용하던 도구라서 익숙했기 때문이죠.
https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)
기본적인 동작에는 문제가 없었지만 특정한 기능을 추가하기 위해 이런저런 플러그인을 사용하면서 나중에는 이게 어떤 식으로 동작하는지 이해하지 못할 상태가 되었습니다. 이전 직장(MongoDB)에서는 이를 지원하는 엔지니어 조직이 있었기 때문에 안정적으로 플러그인 기능을 추가할 수 있었는데 지금은 아무도 그 일을 해줄 수가 없고 스스로 알아서 해야 하는 상황입니다. 스핑크스(Sphinx)는 파이썬 문서화에 주로 사용되고 있는데, MinIO는 파이썬을 사용하지 않기 때문에(없지는 않았지만 지원을 받을 수는 없는 상황) 일부 원하는 동작과 맞지 않는 부분도 있었습니다.
제품에서 쿠버네티스에 대한 지원이 추가되면서 제품 버전을 분리할 필요가 생겼습니다. 초기 작업은 어렵지 않았습니다. 콘텐츠를 참조하는 구조를 만들고 2개의 사이트로 배포하는 작업이니깐요. 하지만 2개 버전이 릴리스 되는 주기가 달라지면서 콘텐츠를 참조하는 전략이 전혀 먹히지 않았습니다. 문서 동기화도 어려운 상황이었습니다. 문서 내 참조 구조는 점점 복잡해지고 외부 의존성까지 생기면서 건드릴 수 없는 괴물이 되어버렸죠.
그래서 휴고(Hugo)로 전환하는 것을 검토했습니다. 휴고는 go 언어 기반으로 동작하는데 다행히 내부 엔지니어들이 익숙한 방식이라 도움을 받을 수 있었습니다. 일단 복잡하지 않는 제품군부터 전환을 시작했습니다. 현재는 기존 문서를 유지하면서 점진적으로 휴고로 이전하는 전략을 선택하고 있습니다.
문서 도구를 선택할 때의 팁:
문서 도구가 내부적으로(기술적으로) 어떻게 동작하는지 이해할 필요는 없습니다. 다만 필요한 기능을 작은 단위로 구현해 보고 이게 맞는 방식인지는 평가해주어야 합니다. 너무 많은 이해관계자의 요구사항을 맞추지는 말고 문서를 공개할 수준으로 만들고 마케팅에서 원하는 디자인 정도만 구현 가능한지 확인하고 진행하면 됩니다. 그 이후의 요구사항은 천천히 맞추어 가는 것이 좋습니다. 완벽한 도구 체인은 없고 언젠가는 문제가 될 수 있습니다.
싱글 소스의 문제점:
싱글 소스를 처리하는 로직이 복잡해지면서 오류가 발생할 수 있습니다. 이런 오류로 인해 전혀 잘못된 내용이 전달될 수도 있죠. 때문에 민감한 정보를 다루어야 한다면 싱글 소스 방식이 적합하지 않을 수도 있습니다.
문서 도구의 지원 종료:
오픈 소스를 사용하더라도 개발이 중단되고 1년이 넘는 시간이 지났다면 다른 도구로 넘어가는 것을 검토해야 합니다. 앞에서 언급한 것처럼 언젠가는 문제가 생기는데 그걸 대응할 수 없다는 이야기거든요.
https://charts.min.io/
https://min.io/docs/minio/kubernetes/upstream/
6 Embrace the Kraken
www.flickr.com
https://youtu.be/etEZhIjoumc?si=hCER7P08Me7d08Yp
