좋은 기술 문서가 필요한 3가지 이유

첫째, 문서는 기업의 수준을 보여줍니다.

기술 문서를 아무리 잘 써 놓아도 어차피 고객은 보지 않을 것이라 생각하는 사람이 있을 수 있습니다. 문서가 달라봐야 얼마나 다르겠어라고 느낄 수도 있습니다. 하지만 분명 다릅니다. 잘 쓰인 문서와 아닌 문서는 차이가 있습니다. 기업의 공식 문서에 오탈자, 맞춤법, 띄어쓰기가 지켜지지 않은 경우가 있습니다. 고객이 그러한 공식 문서를 보면 어떤 생각이 들까요? '이 기업은 기본적인 어법조차 지키지 않는구나, 과연 서비스는 제대로 할까?'라고 생각할 수도 있습니다. 좋은 기업은 디테일까지 꼼꼼하게 챙겨야 합니다. 그래야만 신뢰성을 유지할 수 있습니다.

둘째, 잘 쓰인 문서는 기업과 고객의 시간을 덜어줍니다.

제품을 사용하다 막히는 부분이 있다고 가정해 봅시다. 가장 쉬운 방법은 고객센터에 문의해서 질문에 대한 해답을 찾는 것입니다. 문제는 정리된 문서가 없거나 혹은 문서에 최신 사항이 제대로 업데이트돼있지 않을 때입니다. 고객 서비스 담당자는 매번 같은 문의가 들어올 때마다 직접 답변을 해줘야 합니다. 정리된 문서가 없기 때문에 담당자를 찾고, 확인하는 과정에서 시간이 소요됩니다. 결국 악순환이 반복되는 셈입니다.

고객 입장에서도 난감하긴 마찬가지입니다. 때로는 답변을 기다리는 것보단 관련 문서를 직접 찾아보는 게 훨씬 빠릅니다. 하지만, 아무리 찾아봐도 해결 방법이 안 나오면 어떨까요? 읽어봐도 무슨 말인지 모르겠다면 당황스러울 겁니다. 심지어 고객센터에 연락해도 바로 답변이 안 온다면 얼마나 답답할까요? 고객 경험에 부정적인 영향을 미치게 될 것입니다.

마지막으로, 문서는 기업의 자산입니다.

물론 좋은 제품을 개발하는 것이 중요합니다. 하지만, 그에 못지않게 개발한 제품에 대한 올바른 사용 방법과 과정을 기록으로 남기는 것 역시 빠질 수 없는 과정입니다. '개발자한테 직접 물어보면 되지 왜 꼭 문서로 정리를 해야 하나요? 너무 바쁘고 귀찮은데요.'라고 생각할 수도 있습니다.

그렇지만 필요할 때마다 개발자에게 직접 물어봐야 한다면 결국 더 많은 비용을 초래하게 됩니다. 더구나 만약 개발자가 퇴사한다면 어떻게 될까요? 개발자가 개인적인 사정이 있어서 당장 연락이 안 된다면 또 어떻게 대처해야 할까요? 기업 규모가 커질수록 기록을 문서로 남겨야 합니다. 담당자에게만 의지하면 긴급한 일이 있을 때 일이 더 커질 수 있습니다.

와탭의 기술 문서 개편 과정

1. 기술 문서 구조 재구성

문서 세부 메뉴를 통합했습니다.

기존에는 메인 페이지에서 문서를 누르면 하위 메뉴로 지원 홈, 문서, 릴리즈 노트, 고객 지원이 나오는 구조였습니다. 가이드 문서를 보려면 문서 메뉴를 누르고 또다시 문서를 클릭해야 해서 번거롭다는 의견이 있었습니다.

현재 개편한 문서 구조에서는 메인 페이지에서 문서 메뉴를 누르면 기술 문서 페이지가 새 창으로 뜹니다. 릴리즈 노트는 문서 페이지 안에 포함되어 있습니다. 활용도가 떨어지던 기존 통합 형식의 고객 지원 페이지(FAQ)는 각 관련 카테고리 안에 세부 목차로 포함시켰습니다. 예를 들어, Java 에이전트 설치 관련한 트러블슈팅 방법은 관련 메뉴인 설치하기에서 확인할 수 있습니다.

어떤 에이전트를 설치하든 공통적으로 거쳐야 하는 과정이 있습니다. 예를 들면, 회원 가입을 하고, 프로젝트 생성 후 라이선스를 발급하는 것인데요. 이러한 필수 단계를 각 언어별 에이전트 문서에 매번 넣는 것이 아니라 시작하기라는 카테고리로 분리했습니다.

2. 사용성 테스트 후 문서에 즉각 반영

개발자가 새로운 기능이 개발하면 테크니컬 라이터는 배포 시점에 맞춰 가이드 문서를 준비합니다. (상황에 따라 다를 수 있지만) 데브옵스팀에서 기본 개념에 대한 설명을 작성하면, 프론트 파트에서는 UI에 대한 사용법을 작성하는 식입니다.

이때 테크니컬 라이터는 새로운 기능을 직접 테스트해 봅니다. 사용해 보면서 가이드 문서와 불일치하는 내용은 없는지 꼼꼼하게 확인해 봅니다. 예를 들면, 개발 과정에서 화면에서의 메뉴 이름이 변경됐지만 가이드 문서에는 반영되지 않은 경우가 있습니다. 이런 세부 사항들을 꼼꼼히 확인해 보면서 가이드 문서를 다듬는 과정을 거칩니다. 이때, 오탈자나 맞춤법 역시 확인합니다.

뿐만 아니라, 제가 사용자라면 어떤 내용이 궁금할지 고민해 보고 가이드에 내용을 추가합니다. 최근에 새로 개발된 로그 모니터링이라는 기능이 있는데요. 로그 모니터링에서는 로그 조회 비밀번호를 설정할 수 있었습니다. 처음 받은 가이드 초안에서는 로그 조회 비밀번호를 왜 쓰는 건지, 누가 설정할 수 있는 건지, 비밀번호를 잊어버리면 어떻게 수정할 수 있는지 내용이 빠져있었습니다. 이렇게 누락된 내용은 개발자와 확인 후 가이드에 적용합니다.

3. 끊임없는 내부 피드백 수집

좋은 문서를 만들기 위해선 여러 사람이 힘을 합쳐야 합니다. 테크니컬 라이터 혼자서 모든 것을 챙기기는 어렵습니다. 제가 속한 데브옵스 팀뿐만 아니라 관련 팀 구성원들의 피드백을 받고 문서에 즉각 반영하고 있습니다. 반영 후에는 기술 문서에서 업데이트된 부분을 고객을 직접 상대하는 담당자에게 공유합니다.

4. 관련 문서 링크 추가

이전에는 Service 릴리즈 노트에 어떤 새로운 기능이 추가되었는지 목록만 나와있었습니다. 현재는 릴리즈 노트에 관련 기능에 관한 설명 링크를 걸어두었습니다. 예를 들어, 2021-10-06에 올라온 Service 1.50.0 릴리즈 노트에는 통합 보고서 기능이 추가됐습니다. 릴리즈 노트 내용에서 통합 보고서 단어를 클릭하면 가이드 문서에 관련 설명이 있는 곳으로 이동합니다. 이처럼 사용자는 릴리즈 노트에서 신규 기능이 뭐가 있는지 살펴본 후 링크를 통해 보다 자세한 내용을 파악할 수 있습니다.

이 외에도 사용자가 원하는 문서를 쉽게 찾을 수 있게 UX를 고민하고 있습니다. 좋은 기술 문서는 내용뿐만 아니라 보기 편한 배치, 디자인 등이 갖춰져야 합니다. 와탭에서는 좋은 기술 문서를 만들기 위해 데브옵스팀 테크니컬 라이터, 엔지니어, 프론트 파트 개발자, 디자이너가 모두 힘쓰고 있습니다.

기술 문서와 관련해서 의견 있으시면 언제든지 말씀해 주세요 😉
[email protected]으로 메일 보내주시거나 와탭랩스 온라인 고객지원을 통해 얘기해 주시면 됩니다.
고객님들이 좋은 기술 문서로 와탭 제품을 더 손쉽게 사용할 수 있도록 최선을 다하겠습니다.