kong 문서 팀은 6명으로 구성되어 있습디다. 5명의 테크니컬 라이터와 1명의 도큐먼트 엔지니어가 일하고 있습니다. 이 팀에서 13명의 PM과 150여명의 개발 엔지니어. 30여명의 지원 엔지니어와 함께 문서화 작업을 진행합니다.
문서 팀에서 다루어야 할 업무가 점점 많아지고 있어서 가능한 반복적인 작업은 자동화할 수 있도록 노력하고 있습니다. 그 중 하나가 다이어그램이었습니다.
다이어그램을 위해 사용하는 프로그램은 한 가지가 아니었습니다. Figma, Miro, Lucidchart, draw.io 같은 도구를 사용하고 있었습니다. 그리고 그 외에 다른 도구를 사용하기도 했습니다.
https://www.figma.com/resource-library/diagramming/
https://miro.com/diagramming/
https://www.lucidchart.com/pages/landing/diagram-software
https://draw.io
다른 도구를 사용하게 되면 일관된 스타일을 유지하기 어렵고 수정 사항을 반영하기도 쉽지 않습니다. 또 특정 도구에 익숙하지 않은 경우 도구 사용법을 새로 배워야 하는 일도 생길 수 있습니다. Figma 처럼 유료로 사용해야 하는 도구는 라이선스가 사내에서 사용할 수 있는 라이선스가 한정되어 있어서 바로 작업을 하지 못할 수도 있습니다. 설상가상으로 회사 내 비용 절감을 이유로 Figma 라이선스를 더 이상 지원하지 않으면서 Figma로 만든 콘텐츠를 수정하지 못하는 상황이 되어버렸습니다. 그리고 얼마 후 Miro와 LucidChart에 대한 지원도 중단했습니다.
그래서 다이어그램 작성을 마케팅팀에 의뢰하기로 했습니다. 마케팅팀은 회사 내 디자인의 원칙을 가지고 있으며 일관된 결과물을 만들 수 있으니 문서팀보다는 나을 것이라 생각했습니다. 하지만 프로세스 문제가 있었습니다. 마케팅팀 입장에서는 다이어그램 작성이 우선 순위가 아닐 수 있고 피드백이 오고 가는 과정에서 일정이 많이 지연되었습니다.
대안으로 찾은 것 중 하나는 구글 슬라이드입니다. 템플릿을 제공하고 일관성 있는 테마를 적용할 수 있는 장점은 있습니다. 하지만 여전히 다루기가 쉽지 않습니다. 그래서 대안으로 스크립트 기반으로 다이어그램을 생성할 수 있는 Mermaid를 선택했습니다.
https://mermaid.js.org/
Jekyll 플러그인으로 공개된 리소스 중에서 적당한 것을 찾아서 요구사항에 맞게 개선을 했습니다(도큐먼트 엔지니어가 있었기 때문에 작업을 수월하게 했지만 그렇지 않더라도 워낙 많은 리소스가 있어서 어렵지는 않았을 것 같습니다).
2023년 10월에 도입을 위한 검토를 진행했고 11월에 POC, 12월에 실제 운영 문서에 반영했습니다(물론 이전 디자이너가 작업한 다이어그램에 비해 그럴듯하게 보이지는 않습니다만 이쁜 디자인보다는 문서 전체에서 일관성을 유지할 수 있는 것이 더 큰 이점이라고 합니다). 마크다운 문서 내에 memaid.js를 위한 스크립트만 추가하면 다이어그램을 문서와 같이 배포할 수 있습니다.
문서 팀 뿐 아니라 다른 조직에서도 Mermaid를 사용해 문서를 작성한다면 일관성을 유지할 수 있게 스타일 가이드도 제공하고 있습니다.
https://docs.konghq.com/contributing/diagrams/
kong에서는 kuma라는 오픈소스에 기여하고 있는데 여기에 사용하는 문서에도 Mermaid를 사용할 수 있도록 했습니다. 하지만 kuma 팀에서는 구글 슬라이드를 사용하고 있어서 약간의 충돌이 있었습니다. 하지만 kong 문서팀은 kuma 팀과 오랜 기간 좋은 신뢰 관계를 맺고 있었고 Mermaid를 사용하는 이점을 설득하는데 큰 어려움은 없었습니다.
https://github.com/kumahq/kuma
실제 Mermaid를 발견(?)한 것은 2022년인데 그때는 그냥 이런 솔루션이 있어라는 느낌으로 관련 링크만 공유를 해서 실제 행동으로 이어지지 못했습니다. 2023년에는 실제 기능을 확인해보고 바로 POC로 이어지는 과정을 통해서 성과를 낼 수 있었습니다.
* mermaid.js는 MIT 라이선스로 공개된 오픈소스지만 최근 AI를 지원하는 mermaid chart pro라는 제품이 나왔습니다.
https://www.mermaidchart.com/landing
https://youtu.be/PUwg-rWeeCg?si=K84y2WhizW0imsPA
Were Writers Not Designers
www.flickr.com
