2023. 4. 19. 11:48ㆍ어쩌다 IT/Product & Web Publishing
최근에 서비스 인증서 관련으로 급하게 매뉴얼을 작성할 일이 있었습니다. 주어진 시간이 많지 않았기에 직접 빠르게 사용해보며 플랫폼을 결정하게 되었는데, 그 과정을 글로 담아보았습니다.
Docs Tool 선택 기준
우선 후보군에는 제로하이트(zeroheight) / 깃북(GitBook) / 리드미(readme) / 노션(Notion) 등이 있었습니다. 이 네가지 툴은 경쟁사의 매뉴얼과, 비슷한 도메인의 매뉴얼을 레퍼런스 삼아 선정하였습니다. 그렇게 매뉴얼을 작성할 서비스를 추린 후에는 아래의 기준으로 최종 선별하였습니다.
1. 가격 (Pricing)
저희 팀이 깃북을 선택한 이유에는 사실 이 부분이 7할을 차지한다고 보아도 무방합니다. 우리 서비스는 수요 조직의 특정 롤(role)만 사용하는 B2B/B2G 서비스로, 매뉴얼에 큰 금액을 지불할만큼 서비스 이용자가 많지 않으며 우리 기업의 재정도 넉넉하지 않은 편이기 때문입니다. 따라서 적은 금액으로 매뉴얼을 유지할 수 있는 서비스가 최우선적이었습니다. 개인적으로는 제로하이트를 선호하였으나, 안타깝게도 압도적인 금액 차이로 인하여 깃북과 노션으로 어느정도 선택지가 좁혀졌습니다. (추후 한가지 툴을 선택하여 API, 디자인시스템 문서로 확장시킬 계획도 있었기에 장기적으로도 이득인 것 또한 고려하였습니다.)
* 무료 플랜 바로 상위 플랜 / Annually 기준 / 2023년 4월 기준
| 제로하이트(zeroheight) | 깃북(GitBook) | 리드미(readme) | 노션(Notion) | |
| Pricing | $49 / per editor | $6.70 / per editor | $99 / per project | $8 / per editor |
| 비고 | Sales tax 별도 | Pro 요금제부터 Platform fee 부과 |
프로젝트 당 요금 부과 (인당 x) | - |
2. 작업 용이성
동시작업
저희는 저와 PM동료 두 명이서 작업하였기 때문에, 두 사용자가 동시에 작업하였을 때 무리가 없어야 했습니다. 완전한 라이브 에디팅은 노션이 가장 훌륭했고, 나머지는 타협이 가능한 정도였습니다. 깃북은 퍼블리쉬 상태에서는 동시작업이 힘들고, 각각 작업하고 추후 머지(merge)하는 방식이었는데, 문서가 웹에 퍼블리쉬된 상태가 아니더라도 2명이상의 사용자가 동시에 같은 페이지를 에디팅 하는 것은 불가능했습니다.
PDF 출력
위에서 언급하였듯 제가 맡은 서비스는 B2B/B2G로, 종종 보수적이고 강제적인 상황에 맞닥뜨리는 경우가 있었습니다. 그러한 상황 중 하나가 무엇이든, 언제든 산출물을 프린트하거나 로컬 문서로 전달해야할 수 있다는 것인데, 추후 곤란한 상황에 놓이지 않도록 'PDF로 뽑을 수 있는가'도 하나의 고려 대상이었습니다. 지금 당장의 요구사항이 아니기에 툴 선택에 중요한 요소는 아니었지만, 확인해본 결과 모두 PDF 출력이 가능하였습니다. 다만 노션은 PDF 출력 품질이 매우 떨어졌고, 제로하이트/깃북/리드미는 훌륭한 품질이지만 높은 요금제에서만 출력이 가능했습니다.
3. 가독성 / 독자 편의성
이부분으로 인해 노션이 후보군에서 최종 탈락하게되었습니다. 작성하려는 문서가 '매뉴얼'이다보니 무조건적으로 1.잘 읽히고, 2.잘 찾을 수 있어야 했는데 노션은 훌륭한 툴임은 확실하지만, 공식적인 매뉴얼을 작성하기에는 다른 툴에 비해 정리감이 아쉬운 부분이 있었습니다. 포맷이 어느정도 정해져 있는 타 툴에 비하여 노션은 형식이 자유로운만큼, 페이지네이션(Pagination) 을 수동으로 넣어주어야 하거나 목차 활용이 어려웠습니다. (개인적으로 마크다운 작성법에 의해 생성된 목차가 사이드에 Sticky되는 것을 간절히 바랬습니다 😂)
아래 검색 예시만 보아도 알 수 있듯, 노션은 계층 간 구분이 타 문서 툴에 비해 부족한 부분이 있었습니다. 게다가 각 페이지에 아이콘을 부여한 상태라면? 기본 아이콘과 추가한 아이콘이 뒤섞여 더 구분이 어렵게 됩니다. 이는 즉, 독자가 검색 기능을 활용하여 원하는 설명을 찾기가 더 어려워진다는 것입니다.
깃북(GitBook) 장단점
🔵 Pros
가격경쟁력
저희와 같이 작은 규모의 기업에서 쓰기엔 확실히 가격경쟁력이 있습니다. 다만, 작업자가 많은 조직이라면 다시 생각해보기를 권장합니다. 애널리틱스, 자유도가 높은 커스터마이징, 더 다양한 롤 부여 등이 가능한 Pro 요금제부터는 매달 Platform fee가 추가로 붙어 가격경쟁력이 크게 느껴지지 않을 수 있습니다.
우수한 검색도구
원하는 정보의 위치를 인지하고 도달하기까지는 GitBook < readme < zeroheight < notion 순으로 시간이 소요되었습니다. 이는 '맥락'의 파악이 가장 중요한 역할을 했는데, 가령 가상 서비스의 '필터'에 대한 정보를 찾고 싶다고 해보겠습니다. 그렇다면 내가 원하는 설명이 '프로젝트'에 있는 필터에 대한 것인지, 그 바깥의 '워크스페이스'에 있는 필터인지를 검색도구 사용 시 잘 알 수 있어야 합니다. GitBook의 검색도구는 MUI와 같은 방식으로, 계층 간 구조를 들여쓰기 방식을 통해 확실하게 보여주고 있습니다.
🔴 Cons
한글 친화적이지 못한 서비스
가장 치명적인 부분입니다. 퍼블리쉬된 상태에서는 텍스트 수정이 거의 안된다고 봐야합니다. 저희는 두 명이 동시에 작업하였기 때문에 퍼블리쉬하지 않고 작업하였는데(퍼블리쉬하면 동시 작업이 불가능합니다), 그럼에도 불구하고 이미지에 캡션 달기는 불가능에 가까워 메모장에 적고, 복붙하기를 반복했으며 윈도우를 쓰는 동료는 텍스트가 종종 이상한 글자로 변형되어 괴로워하기도 했습니다. macOS를 사용중인 저 또한 계속 글자가 씹히고 백스페이스가 안먹히는 기가막히는 현상을 경험했습니다.
페이지 제한
아래의 예시는 Zeroheight의 문서인데, GNB / LNB / Contents 영역이 나뉘어져 있는 것을 확인할 수 있습니다. GitBook은 언뜻 보면 비슷한 구조로 보이나, GNB Menu 위치에 있는 것이 GNB가 아닌 단순 태그에 불과합니다. 각 GNB 위치에 넣을 수 있는 menu가 각각 하나의 페이지를 가지고 있는 것이 아닌, 특정 LNB 메뉴로의 이동이거나, 외부 페이지로 나가는 링크로만 지정할 수 있습니다. 이런 이유로 처음에 개념을 익히는 데에 잠시 어려움이 있었으며, 매뉴얼 단위 쪼개기에 아쉬움이 남았습니다.
개발 이외 직군에게는 개념 공부가 필요한 서비스
깃헙(github)에서 만든 서비스답게 깃헙의 시스템을 그대로 가지고 왔습니다. 업무 중 깃헙을 몇 번 써보며 아주 조금은 깃헙과 가까워졌다고 생각했는데, 경기도 오산이었습니다. 브랜치, 커밋, 머지!만 앵무새처럼 외치던 저에게는 Follow up / in review / Draft / Merge 각각의 개념을 정확하게 이해하고, 적용하는데에는 시간이 필요했습니다. 개발자들에게는 숨쉬듯이 하는 과정이지만, 이외의 직군에게는 초기에 힘들 수도 있다고 생각합니다(물론 아직 제가 부족한 것도 인정합니다).
디자이너가 직접 매뉴얼을 작성하면 좋은 점
1. 자신이 설계한 서비스 플로우를 객관적인 눈으로 볼 수 있다.
실무에 뛰어들고 나면, 사이드프로젝트를 하거나 개인 연습을 할 때 처럼 여유롭게 프로토타이핑을 할 시간이 없습니다. 게다가 유지보수가 아닌 구축 프로젝트에선 페이지의 양도 많거니와 신경써야할 부분이 많아 세세한 부분의 플로우를 놓치기 쉽습니다. 디자이너가 매뉴얼을 작성하면, 연관된 페이지를 링크하고 흐름을 설명하면서 ‘여기서 여기로 가는게 자연스러운가?’를 끊임없이 관찰하게 됩니다.
2. 무(無)의 눈으로 바라볼 수 있다.
매뉴얼을 작성하면 ‘이렇게까지 해야하나’ 싶을정도로 작은 부분, 당연해보이는 부분도 글로 작성하게 됩니다. 정말 ‘아무것도 모르는’ 사람의 시점에서 설명하기 때문에 내 작업물을 객관적으로 바라볼 수 있게 됩니다. 종종 제이콥의 법칙을 운운하며 사실은 사용자보다 나 자신에게 익숙한 UI를 사용하여 빠르게 넘어갈 때가 있는데, 이런 부분을 발견하고 인지해두면 추후 유지보수 시 바로잡을 수 있습니다.
3. 따로 시간을 내지 않아도 되는 회고의 시간
매뉴얼 작성에는 기능 기본 설명 뿐만이 아니라, 유저가 맞닥뜨릴 여러 당황스러운 상황을 상상하여 해결책을 미리 적어두는 것도 포함됩니다. 그래서 캡쳐와 설명을 위해 이것저것 시도해보면, 내가 고려하지 못했던 State나 개발상의 버그를 찾아낼 수도 있습니다. 가벼운 QA를 한 셈이죠. 또한 유저가 느낄 페인포인트들을 피부로 직접 느낄 수 있기에 업무 외 시간에 따로 시간을 내어 회고하지 않아도 반성이 되고, 앞으로 나아가야할 방향을 설정할 수 있습니다.
마무리
장황하게 늘어놨지만, 역시나 가장 좋은 툴은 '우리 기업(조직)의 상황 / 사용하려는 용도 / 도달하고자 하는 목표에 맞는 툴'입니다. 오늘 쓴 이 내용은 깃헙을 추천하거나 비추천하고자 함이 아니기에, 읽는 분들께서 필요로 하는 툴은 어떤 것이 적합한가 잘 따져보기를 바랍니다. 마지막으로 도움이 될까하여, 하이크(hike)에서 정리한 비교표를 함께 첨부하며 글을 마무리해볼까 합니다. 고민 중인 누군가에게 좋은 참고가 되었으면 좋겠습니다 :)
