시작하며
안녕하세요. 어느덧 2020년 가을이 되어 테크니컬라이팅팀에서 벌써 세 번째 포스팅을 올리게 되었습니다. 그동안 테크니컬커뮤니케이션에 대한 소개와 기술 문서 작성 5단계라는 주제를 다뤘는데요. 오늘은 "카카오 i 기술문서 사이트(https://docs.kakaoi.ai)"가 오픈한 지 한 달을 맞이하여, 기술문서 사이트의 구축 배경과 실제 릴리즈까지의 고민과 여정을 여러분들과 공유해 볼까 합니다.
혹시 테크니컬 라이터라고 하면 단지 문서만 작성하고 관리한다고 생각하시는 분들이 계실 수도 있는데요. 요즘은 IT 기업들의 문서화 트렌드에 따라, 종이 버전이나 PDF 버전을 벗어나 웹에 문서를 게시하는 과정의 중심에 테크니컬 라이터의 역할이 한층 강조되고 있습니다. 이처럼 기술문서 게시를 위한 웹 사이트 구축을 고민하고 있는 기업의 테크니컬 라이터 분들이라면 이번 포스팅이 더욱 뜻깊게 와닿지 않을까 생각되는데요. 저희의 경험이 조금이나마 도움이 되었으면 하는 바람으로 글을 시작하도록 하겠습니다.
기술문서 사이트, 선택이 아닌 필수
사실 카카오 i 기술문서 사이트 구축은 카카오엔터프라이즈에 테크니컬라이팅팀이 처음 세팅된 2019년 하반기부터 주어졌던 과제였습니다. 당시 외부 개발자에게 배포해야 하는 API 레퍼런스나 SDK 가이드 등의 기술문서는 점점 많아지고 있는데, 그 문서들을 게시할 공식적인 기술문서 사이트가 없었던 것이죠. 향후 카카오엔터프라이즈에서 다양한 서비스가 출시될 것을 고려했을 때, 서비스 출시에 발맞춰 외부 개발자들에게 전달할 기술문서를 공유할 플랫폼 선정과 제공할 가이드 마련이 시급했습니다.
기술문서 사이트의 필요성
테크니컬라이팅팀이 세팅되기 전에는 개발자들은 구글 문서 도구, Jira, Wiki 페이지 또는 MS Office 문서를 PDF 형식으로 변환하여 외부 개발자들에게 전달했다고 합니다. 기술문서는 일반 문서와 비교했을 때 업데이트 주기가 짧다는 사실을 차치하더라도, 이렇게 PDF로 문서를 변환하면 문서 서식 변형과 페이지 분리로 인한 사용성 저하라는 큰 문제에 직면하게 됩니다. 10페이지 내외의 짧은 문서라면 문제가 없지만, 만약 100페이지가 넘어가게 된다면 제목이나 넘버링 등의 서식이 빈번하게 깨지고, 이런 서식들을 수동으로 일일이 수정한다고 해도 서식 깨짐이 계속 반복되는 무한 루프에 빠지게 됩니다. 또한 코드블록이나 테이블이 한 페이지를 넘어갈 경우, 정보의 흐름이 끊기고, 정보가 한눈에 들어오지 않아 가독성이 크게 저하되고, 해당 문서의 사용성에 치명적인 타격을 주게 됩니다. 내용이 아무리 정확하고 좋더라도 읽기 어렵고, 사용하기 어려우며, 읽기 싫은 문서가 되는 것입니다.
이러한 문제를 해결하기 위해 저희는 하루빨리 기술문서 웹 사이트를 구축해야 했습니다. 웹 사이트에 기술문서를 게시할 때의 장점은 정말 많지만, 몇 가지만 언급해 보겠습니다.
첫 번째, 기술문서 사이트가 있다면 누구나 원할 때 해당 링크를 통해 기술문서를 열람할 수 있고, 업데이트 또한 실시간으로 가능하기 때문에 독자에게 언제나 정확한 정보를 제공할 수 있습니다.
두 번째, 문서가 업데이트된 경우 "문서가 업데이트되었으니, 해당 이메일에 첨부된 PDF 파일을 참고해 주세요" 등의 내용을 구구절절 이메일로 전달할 필요도 없습니다.
또한 세 번째, 서식 깨짐이나 페이지 분리로 인한 가독성 저하가 없기 때문에, 더욱 가독성 좋은 문서를 릴리즈할 수 있습니다.
그리고 이 밖에도 GIF나 동영상 튜토리얼 등 다양한 리소스를 통해 독자에게 다양한 형식으로 정보를 제공할 수 있으며, API 레퍼런스 문서의 경우 Stoplight나 Swagger UI 등을 연동할 수도 있습니다.
기술문서 사이트 리서치
좋은 기술문서 사이트란
저희는 카카오 i 기술문서 사이트를 본격적으로 구축하기에 앞서, Google Developers, Amazon Developer와 같은 글로벌 IT 기업들의 개발자 문서 사이트를 면밀히 조사하고 분석했습니다. 그리고 좋은 기술문서 사이트란 '글, 이미지 또는 동영상 등의 다양한 형태로 개발 가이드라인을 제공하고, 일관된 스타일 가이드를 준수하여 가독성이 좋은 문서를 제공함으로써 자사의 상품이나 서비스의 개발을 도와줄 수 있는 도구'라고 정의 내렸습니다. 또한 이를 만족하는 동시에 내부적으로 문서의 운영, 배포, 관리를 보다 효율적으로 수행할 수 있어야 한다고 판단하고 이런 요소들을 모두 충족할 수 있는 기술문서 사이트의 구축을 기획했습니다.
초안 작성 도구에 대한 고민
저희는 타사의 기술문서 사이트를 리서치하는 동시에 최적의 초안 작성 도구에 대한 리서치도 병행해야 했습니다. 앞서 잠깐 언급했지만, Google 문서 도구나 MS Office 등에서 초안을 작성하는 방식은 서식 깨짐, 가독성 저하, 효율성 저하라는 치명적인 문제가 있었기 때문입니다.
사실 기술문서의 웹 퍼블리싱에 대해 깊게 리서치를 시작하기 전에는, 동일한 툴에서 초안 작성을 하고 이를 저희의 스타일 요구사항에 맞게 웹에 완벽하게 퍼블리싱해 줄 수 있는 마법의 툴이 있을 것이라고 기대했습니다. 실제 이렇게 기술문서의 웹 퍼블리싱을 가능하게 해주는 툴로 Gitbook, Paligo, Madcap Flare 등을 검토해 봤지만, 아쉽게도 저희의 요구사항을 모두 만족시켜주는 툴은 찾을 수 없었습니다. 예를 들어, A라는 툴에서는 코드 블록의 다크 모드 기능이 지원되지만 협업을 위한 메모 기능은 지원되지 않았으며, B라는 툴에서는 이런 기능들은 모두 지원하지만 템플릿 스타일을 커스터마이징할 수 없는 등의 문제가 있었던 것입니다.
결국 TF에서 논의 끝에 Hugo라는 정적사이트생성기를 사용해 Markdown(마크다운) 파일 형식(.md)으로 문서를 작성하고 Git으로 관리하는 방법을 채택했습니다. 저희의 요구사항 중 Hugo가 지원하지 않는 기능은 자체 개발을 통해 구현하기로 결정했습니다.
기술문서 사이트의 가이드라인 수립
기술문서를 웹 사이트에 공개할 때, 문서의 품질이 곧 회사의 이미지와 신뢰도에도 영향을 줄 수 있기 때문에 문서화 스타일에 대한 가이드라인도 수립해야 했습니다. Google 문서 도구에는 한 문서에 100페이지 분량을 모두 구성했다면, 웹 사이트에서는 챕터별, 주제별, 모듈별로 문서의 구성, 트리 구조 등을 다르게 해야 했습니다. 또한 큰 틀에서 서비스별 문서 구성, 각 문서의 챕터별 구성 요소, 구성 요소별 스타일 서식 등을 체계적으로 점검하고 관련 스타일을 수립했습니다. 로컬 환경에서 Hugo 서버를 통해 정적 사이트를 생성하고 페이지별로 시뮬레이션을 해 보면서 최적의 스타일에 대해 지속적인 논의를 진행했고, 기술문서의 일관된 스타일을 제공하기 위해 Markdown 사용 가이드와 기술문서 스타일 가이드 등을 생성했습니다.
기술문서 템플릿의 구성
개발자들과의 초안 작성과 협업을 위해 기술문서 종류별 템플릿도 제작했습니다. 저희 팀에서는 API 레퍼런스 템플릿, 개발 가이드, 트러블슈팅 가이드, SDK 가이드 등 다양한 문서들의 템플릿을 제작하여 내부적으로 공유하고 있는데요. 포스팅에서는 API 레퍼런스 템플릿을 기준으로 소개해 드리도록 하겠습니다.
저희가 제작한 API 레퍼런스 템플릿은 크게 API 개요, API 공통 가이드, API 개별 가이드 섹션으로 구성됩니다. "API 개요"에는 해당 API의 기능을 간략하게 설명하고, 해당 API에서 제공하는 모든 API 종류를 테이블로 정리하여 클릭 시 각 API 별 챕터로 이동할 수 있는 링크를 적용했습니다. "API 공통 가이드"에는 API 인증 및 권한 부여 방법, API 상태 코드와 에러 코드 등을 넣었으며, "API 개별 가이드"에서는 API별로 Request와 Response로 구분했고, API 사용 방법을 기술했습니다.
이렇게 기술문서의 종류별로 템플릿을 제작한 이유는 개발자들과 초안을 주고받을 때 수월하게 협업하고, 궁극적으로 완성도 높은 기술문서를 제작하기 위해서입니다. 이런 템플릿이 없는 상황에서 만약 "API 엔드포인트에 대한 문서를 작성해 주세요"라고 개발자들에게 요청하면 개발자들은 당황할 수 있습니다. 어디서부터 어디까지 정보를 제공해야 할지 막막하기 때문이죠. 따라서 템플릿에 필요한 항목을 사전에 정의하면 개발자와의 협업이 보다 수월해집니다. 템플릿을 만들어 개발자들에게 전달함으로써 요청 예시는 있는데 응답 예시는 누락되어 있거나, 특정 API에서 발생하는 에러 코드 누락 등의 이슈를 예방할 수 있습니다. 또한 템플릿에 모든 항목이 있기 때문에, 개발자들이나 테크니컬 라이터들은 해당 항목을 채우는 작업을 함으로써 완성도 높은 문서를 릴리즈할 수 있습니다.
카카오 i 기술문서 사이트 구축 프로세스
기술문서 사이트 TF가 구성된 것은 올해 상반기였습니다. 이때는 카카오엔터프라이즈의 다양한 서비스 출시 예정에 맞춰 관련 기술문서를 게시할 웹 사이트의 오픈이 더욱 절실히 필요한 시기였습니다. TF가 구성되기 이전에는 내부적으로 기술문서 사이트의 필요성을 인식하고 기술문서 웹 퍼블리싱에 대한 스터디 및 기존의 문서를 개선하는 작업을 진행해 왔다면, 이제는 본격적으로 TF를 구성해서 최대한 빨리 사이트를 오픈해야 했습니다. 이에 따라 테크니컬 라이터, 기획자, 백엔드 및 프론트엔드 개발자, 디자이너, UX 팀이 참여하는 기술문서 사이트 구축 TF가 구성되었습니다. TF에서는 개발, 디자인 등 많은 팀에서 참여해 주셨지만, 이 글에서는 테크니컬 라이터 관점에서 진행했던 단계별 주요 작업 사항을 공유해 보겠습니다.
기획
기획 단계에서는 TF 참여자인 기획팀, 개발팀, 디자인팀, 테크니컬커뮤니케이션팀 각자의 요구사항을 도출하고 분석한 후, 기술문서 사이트 개발을 위한 요구사항 명세서를 작성했습니다. 저희 조직에서는 콘텐츠를 효과적으로 게시하기 위한 요구사항을 정의했는데요. 위에서 잠시 언급했듯이 TF 초창기부터 Google Developers, Amazon Developer와 같은 글로벌 기술문서 사이트를 서치한 후 관련 요구사항을 정리했습니다. "테이블 너비는 자동 정렬로 하고, 헤더는 가운데 정렬로 해 주세요." "코드블록에서 언어별 탭을 추가하고, 다크모드/화이트모드와 복사 기능을 추가해주세요", "페이지 내비게이션은 우측에 항상 고정해주세요" 등 요구 사항을 구체화한 후 기획팀에 전달했습니다. 이를 바탕으로 기획팀에서 프로젝트 상세 기획서를 작성했고, 개발자와 각각의 기능 구현 여부를 확인했습니다. 디자인팀과는 문서 및 사이트 디자인 서식 등을 함께 논의하고 협의하는 과정을 거쳤습니다.
콘텐츠 작성
카카오 i 기술문서 사이트에 게시할 문서는 사전에 구성한 카카오 i 기술문서 템플릿을 바탕으로 Markdown 형식으로 초안을 작성하고, Git에 파일들을 업로드하는 방식으로 진행했습니다. 문서 작성자가 여러 명일 수 있기 때문에 변경사항 관리, 버전 관리도 매우 중요한데, 이런 측면에서 Git은 훌륭한 문서 작성 도구라고 생각됩니다. 콘텐츠는 Technical Writing의 4대 원칙인 명확성, 간결성, 정확성, 일관성에 따라 구성했는데요. 콘텐츠의 내용이 모호하거나 애매하지 않도록 팀 내 피어리뷰를 거쳐 여러 번 검토했고, 핵심을 쉽게 파악할 수 있도록 이미지 자료 등을 적절히 삽입하여 가독성을 개선했습니다. 그리고 이런 과정을 거쳐 "Markdown 사용 가이드"와 "기술문서 스타일 가이드"를 지속적으로 업데이트 함으로써, 일관성 있는 콘텐츠 제작에 집중했습니다. 저희는 내부적으로 콘텐츠 작성 단계를 "개발" 단계로 분류하고 있으며, 다음 단락에서 "베타" 단계와 "리얼" 단계를 살펴보도록 하겠습니다.
웹 퍼블리싱
콘텐츠 작성 단계인 "개발" 단계를 완료한 후, 웹 퍼블리싱의 일환으로 개발한 웹 사이트를 내부 서버에 올려 콘텐츠가 요구 사항대로 게시되었는지 확인하는 품질 검사(QA)를 진행하는 "베타(Beta)" 단계, 실제 웹 사이트에 배포하는 "리얼(Real)" 단계를 진행합니다. 개발 단계에서 Markdown으로 초안을 작성하고 Git 저장소와 연동한 후 로컬 PC에서 작성된 문서 사이트를 확인해보니, 수정해야 할 부분들이 상당히 많았습니다. 예를 들어, 테이블에 API 목록들을 나열했을 때 API 명이 두 줄로 분리된다거나, Heading 1과 설명 간 문장 간격이 너무 넓어서 가독성이 떨어지는 등의 문제인데요. 이런 문제들은 Markdown 파일로 초안을 작성할 때는 파악할 수 없었습니다. 이렇게 개선이 필요한 사항들을 개발팀과 디자인팀과의 논의를 통해 해결해 나갔습니다. 또한 베타 단계에서는 문서 내부 링크 깨짐, 맞춤법 오류, Markdown 문법 오류 등의 사항을 면밀히 점검하고 수정 작업을 진행한 후, 더는 이상이 없다고 판단되는 시점에 실제 웹 사이트에 배포하는 "리얼" 단계로 넘어갔습니다.
사이트 오픈 이후
카카오 i 기술문서 사이트는 9월 16일에 오픈되었습니다. 1차 오픈 때에는 시간적 한계로 인해 검색 기능, 코드 테스트 실행 기능, Swagger 연동 등과 같은 기능을 아쉽게도 모두 구현하지는 못했습니다. 하지만 추후에 진행될 2차 오픈에는 이런 기능들뿐만 아니라 다양한 기능을 제공하기 위해 현재 다방면으로 논의를 지속하고 있습니다. 또한 문서 콘텐츠 측면에서도 현재는 카카오워크 관련 가이드만 제공하고 있지만, 지속적으로 SDK 가이드, 시스템 아키텍처, 오픈빌더, 용어집 등 다양한 기술문서를 제공할 계획입니다. 내부적으로는 스타일 가이드를 지속적으로 업데이트 중이며, 이에 따른 사이트 스타일 업데이트도 함께 진행하고 있습니다.
마치며
이렇게 글을 쓰고 보니 마치 테크니컬 라이터 관점에서 쓴 카카오 i 기술문서 사이트 구축에 대한 회고록이 된 것 같네요. 1차 오픈이라 아직 미흡한 점도 많이 있지만, 앞으로 카카오 i 기술문서 사이트는 지속적인 개선과 다양한 기술문서의 게시를 통해 외부 개발자들에게 최적화된 문서화 경험을 제공할 예정입니다. 카카오 i 기술문서 사이트에 지속적인 관심과 응원 부탁드리며, 추후에 예정된 2차 오픈도 기대해 주시면 감사하겠습니다. 마지막으로 카카오 i 기술문서 사이트 구축을 위해 힘써주신 TF 참여자분들께 감사의 인사를 드리며 글을 마치도록 하겠습니다.
김유리(Crystal)
사용자의 입장에서 생각하고, 개발자와 원활한 소통을 할 수 있는 Communication Skill을 가진 Technical Communicator입니다. 카카오엔터프라이즈의 값진 기술들을 정확하고 명확하게 전달하고, 신뢰를 쌓을 수 있는 문서를 만들고자 합니다.
차신영(Sandy)
산더미처럼 쌓여진 문서 정리, 새로운 문서화 도구 테스트, 그리고 구글링이 취미인 Technical Communicator입니다.
댓글0