이런 발표(또는 글)는 명확합니다. 무엇 무엇을 위한 10가지. 또는 장단점 비교. 같은 것들이죠. 뻔한 이야기만 나온다면 좀 그렇지만 이번 발표의 경우는 경험에 기반해서 선택지를 줄이고 새롭게 뭔가 해야 하는 이들에게는 도움이 되는 글입니다.
발표 내용은 아래 링크에서 자세히 확인할 수 있습니다. 일부는 발표 후에 추가하거나 수정한 내용도 있다고 합니다.
https://github.com/ru-fu/right-tool
문서화 방법론에서는 Docs as code와 CCMS를 비교합니다. CCMS는 꽤 오랜 시간 다양한 업체에서 솔루션을 만들었고 Docs as code는 특정 솔루션보다는 여러 기술의 조합이라 직접 비교하는 것이 적절할까 싶긴 하지만.
개인적인 생각으로는 CCMS 또는 솔루션을 사용하는 경우에는 나중에 다른 솔루션으로 전환하는 것이 쉽지 않습니다. 이미 운영 중인 시스템이고, 솔루션에서 마이그레이션을 지원하면 모를까 그렇지 않다면 다른 대안을 선택하는 것이 어렵습니다.
Docs as code의 단점이 높은 복잡성이라고 하지만, 팀에서 기술적인 지원이 가능하다면 실제 문서 작성자 입장에서는 단점이라고 느끼지 못할 수도 있구요. CCMS의 단점으로 모두 CCMS를 사용해야 한다는 것도 프로세스를 어떻게 정하느냐에 따라 개별적으로 작성된 리소스를 수집해서 CCMS에 통합하는 방식도 가능합니다.
적절한 도구를 선택하는 과정에서 발표자는 다음과 같은 항목을 체크해야 한다고 합니다.
- 팀 (기여자, 전문성)
지금은 혼자서 문서를 작성하고 있다고 하더라도 규모가 커지면 그에 따른 변화가 필요합니다. 이걸 미리 예측한다고 하더라도 이에 대비한 준비를 하는 것은 쉽지 않습니다. 개발 플랫폼도 마찬가지구요. 규모가 커지면 어느 시점에서 조정이 필요합니다. 때문에 현재 시점에서 가장 최적의 선택을 하는 것이 더 좋을 수 있습니다. 기술적인 지원을 받을 수 있는 조직이 있다면 해당 기술을 기반으로 준비하는 것이 좋고, 그렇지 않다면 외부 솔루션을 선택하는 것이 좀 더 현명한 방법입니다. 외부 솔루션을 선택한다고 하더라도 이를 사용하면서 겪을 수 있는 여러 문제들이 있어서 마냥 편한 건 아닙니다.
- 문서(콘텐츠, 배포 방식)
기본적인 문서 재사용은 거의 대부분의 도구가 지원합니다. 하지만 재사용에 조건이나 변수를 사용해야 한다면 그에 대한 기술적인 지원이 필요할 겁니다. 현재 다루는 제품군에 적절한 환경을 만들어야 하는 것이라 기존 솔루션이나 공개된 오픈소스를 그냥 가져다가 사용할 수 있는 환경은 아니구요. 인쇄가 중요한 환경이라면 HTML 기반으로 만들어지는 PDF 파일 또는 문서 형식은 적절하지 않을 수 있습니다(대충 자동으로 변환해 주는 것이라서). 여전히 인디자인이나 인쇄 전문 솔루션이 중요한 이유입니다.
- 구현(기존 인프라, 해야할 일)
기존 프로세스를 확인하고 사용하는 것은 개발 프로세스 내에 문서화를 포함하려고 한다면 중요한 항목입니다. 개발 프로세스와 떨어진 별도의 프로세스를 가지고 간다면 개발팀의 리뷰를 받는 것이 쉽지 않습니다. 문서화를 위한 예산이나 일정, 기존 문서에 대한 변환도 고려해야 할 항목입니다.
발표자는 워드 문서 변환 시 Pandoc을 추천하는데 파이썬에서 쓸 수 있는 pypandoc도 많이 사용하는 듯합니다.
https://pandoc.org/
https://pypi.org/project/pypandoc/
- 전망(단기 전망, 장기 전망)
단기 전망은 처음에 언급한 팀 항목과 거의 유사합니다. 장기 전망은 예측하기 힘들구요.
Ruth Fuchss - The right tool for the job
https://youtu.be/X1gvtMsA2Dc?si=B87r1M9BPu4dCYB0
