나의 첫 테크니컬 라이팅 업무
직무 전환 후, 첫 주 업무는 워드로 작성하던 매뉴얼을 웹 문서로 전환하기 였습니다.
한 번의 제품 출시에 작성해야 하는 매뉴얼은 4가지였는데, 국문·영문·일문 매뉴얼을 제공하고 있기 때문에 총 12개의 워드 파일을 관리해야 하는 구조였습니다. 이전에 FE 개발자로서 일하면서 제품 개발할 때마다 수많은 워드 파일을 관리하는 게 참으로 끔찍한 업무라는 생각을 했었어요. Typst 같은 플랫폼에서 작성하거나 아예 형상관리를 적용하면 관리가 쉬워질거 같다는 생각은 해왔었는데 아쉽게도 당시 문서의 관리 주체가 형상관리에 대한 이해가 부족했고, 새로운 것을 배우기엔 너무 바쁜 환경이었습니다. 그렇게 몇 년이 흘러... 사용자 가이드는 300페이지가 넘는, 문서를 여는 것도 몇십초 기다려야 열리는 부담스러운 파일이 되었습니다.
워드 문서의 문제점
1. 수정이 힘들다
저희 제품은 국문·영문·일문 3가지 매뉴얼을 작성해야 하는데요. 내용이 동일하고, 언어만 다른 다국어 워드 파일은 관리가 매우 까다롭습니다.
파일 하나에 300페이지가 넘기 때문에 세 언어에 능통하지 않은 이상 내용을 수정할 때 정말 헷갈립니다. 특히 일본어를 볼 땐, 뭐가 틀렸는지 보기도 힘들어요. 언어마다 길이가 다르기 때문에 국문에서 130 페이지에 있는 내용이 일문에는 137 페이지에 들어가 있기도 하고, 실수하기 딱 좋은 구조입니다. (실제로 웹 문서로 전환하면서 오번역 된 부분도 많이 잡았습니다.)
그리고 이미지를 한 번 교체하려면 3번의 반복 작업을 해야 합니다. 국문 파일을 열어서 교체하고, 영문 파일을 열어서 교체하고, 마지막으로 일문 파일을 열어서 교체하는데 개발을 해왔던 저에게는 워드 파일 열리는 거 기다리고, 페이지 찾아서 수 십개의 이미지를 교체하는 작업을 반복하는 것이 정말 고역이었습니다.
2. 리뷰가 어렵다
지난 4년간 릴리즈 직전에 문서 오타를 발견해서 재빌드하느라 새벽까지 일했던 경우가 많았는데요. 300페이지 중에 몇 줄씩 찔끔찔끔 수정한 부분만 검수하기가 까다롭기 때문에 발생한 문제였습니다. 놀랍게도 워드에도 리뷰 기능이 있습니다...만 써보면 아실 것 같습니다. 복장 터집니다.
3. 버전 관리가 어렵다
문서라는 것이 날을 하루 잡아서 작업을 끝내버리면 좋지만 아쉽게도 개발 상황에 따라서 중간중간 작업을 해야하기 때문에 최종 버전이 나올 때까지 여러번 작업을 하는 경우가 많습니다.
최종, 최최종, 최최최종
어떤게 최종인지도 잘 모르겠고, 롤백을 하더라도 어떤 버전으로 롤백해야하는지 일일이 까보지 않으면 보기가 힘든 구조였습니다. 처음 인수인계 받았을 때에는 Git 없이 지금까지 어떻게 관리해왔는지 신기하다는 생각이 들었어요. 비 개발자라도 형상관리를 알아두면 업무 효율을 많이 높일 수 있을 것 같습니다.
Docs to Code
워드는 이제 안녕! 👋 본격적으로 웹 문서화하기로 방향을 결정 한 후 한 일은 다음과 같습니다.
- 플랫폼 선정(Docusaurus)
- 워드 내용 이전
- 다국어 적용
- 이미지 통합
- 스크립트 적용
Docusaurus 선정 이유
여러 플랫폼 PoC를 진행하여 최종적으로 Docusaurus를 선정했습니다. 이유는 다음과 같습니다.
- Blog와 Docs 형태로 분리되는 구조
- 다양한 플러그인 제공
- Meta에서 개발하여 지속적으로 관리되는 오픈소스
- 방대한 커뮤니티
Vitepress, Rspress, Mkdocs 등 다른 SSG 를 살펴보았는데 아무래도 첫 웹 문서 전환이다보니 가장 안전한 플랫폼을 선택하게 되었습니다. Vitepress는 이후 다른 제품의 매뉴얼을 제작할 때 사용해보았는데 Docusaurus보다 깔끔하고, 가벼운 문서에 적합한 느낌입니다.
포스트 형태가 구분되면서 txt 파일로 따로 관리되고 있던 릴리스 노트도 웹 문서에 포함시킬 수 있게 되었습니다. (관리 리소스 -1 ✌️)
빠르게 워드 이전하기
워드 내용을 이전할 때에는 하나씩 붙여넣기 하기보다는 pandoc 으로 docx파일을 markdown으로 변환했습니다.
pandoc -f docx {입력 파일.docx} -t markdown -o {출력 파일.md}
# -f : 입력 파일 형식
# -t : 출력 파일 형식
# -o : 결과물
스크립트
개발의 장점은 변수나 함수를 사용해서 반복되는 작업을 줄이는 것에 있습니다. 처음 개발을 배울 때, 변수를 쓰면 100번 할 일을 1번만 하면 된다는 점이 제일 와 닿았었는데요. 문서 전환에서도 제품명이나 회사명, 기능명처럼 고유한 정보들을 변수 처리해두어 일괄 수정이 쉽도록 했습니다.
이미지 크기를 일괄적으로 제어한다거나 제공 국가에 따라 노출하면 안되는 정보를 가린다거나 할 때의 공수를 크게 줄일 수 있었습니다.
어려웠던 것들
개인 블로그도 Docusaurus를 쓰고 있으니까 큰 어려움 없이 진행될 줄 알았는데 생각지 못했던 문제들이 있었습니다.
1. 배포
제품 특성상 오프라인 환경에서도 웹 매뉴얼을 제공해야하고, 외부 노출이 되면 안되기 때문에 클라우드 배포가 아닌 제품에 탑재하는 방식으로 배포해야 했습니다.
Docusaurus는 SPA이므로 JS 번들 파일이 웹 서버를 거치며 실행되어야 hydrate 되며 제대로 보이게 됩니다.
그래서 로컬에서 file: 로 실행하는 것이 아닌 http: 프로토콜을 거쳐야하는 것이죠.
웹 문서는 만들었는데 서빙을 어떻게 해야할지 몰라서 백엔드 개발자분과 여러번 실험을 한 끝에 최종적으로 nginx로 서빙하는 것으로 마무리지었습니다.
배포 부분은 개발 지식이 조금 필요해서 생각보다 어려움이 있었어요.
2. 용량 최적화
다국어 문서에서 중복되어 사용되던 이미지를 하나로 줄이며 용량이 1/3로 줄었지만 그럼에도 여전히 용량 문제는 있었습니다. 매뉴얼을 워드에서 pdf로 추출해서 제공하는 시절에는 몰랐는데 삽입된 이미지 하나하나의 용량이 커서 최종 빌드본 용량이 매우 큰 문제가 있었습니다.
cwebp를 사용해 이미지를 webp 형식으로 변환했고, 795MB에서 160MB까지 용량을 줄였습니다. 이 때 사용한 스크립트로 간단한 데스크톱 앱을 만들었는데 이는 다른 포스트에서 다룰 예정입니다.
3. pdf 추출
인터넷이 제공되지 않는 환경에서도 매뉴얼을 제공해야하기 에 웹 문서를 제공하더라도 pdf를 추출하여 제공해야 했습니다. docusaurus-prince-pdf 플러그인을 사용해서 pdf를 추출하긴 했지만 섬세한 줄바꿈 같은 것들이 불가능해서 조금 아쉬움은 남습니다.
그리고 pdf 추출 방식이 굉장히 개발 친화적인 느낌이라 비개발자가 업무 인수인계를 받는다면 꽤 난이도가 있을 것 같아서 좀 더 좋은 방법을 찾아야하는 과제처럼 느껴지는 부분입니다.
느낀 점
생각지 못했던 어려움들은 있었지만 FE 개발 업무를 하면서 늘 하고 싶었던 문서 형상 관리를 제대로 해보고, 실제로 많은 개선을 이뤄내서 좋았습니다. 그리고 웹 문서가 탑재된 버전이 출시된 이후 비즈팀에서 반응이 좋아서 놀랍기도 했어요. 진작 할 걸! 신규 입사자분들이 제품 사용할 때, 웹 문서를 사용하는 걸 보면 흐뭇합니다☺️
이제 뭘 Git에 올려볼까?
즐겨보는 웹툰에서 개발자가 다른 직무의 업무를 할 때, 모든 것을 Git에 올리려 할 것이라는 장면을 봤을 때 너무 공감이 되어 웃겼는데요 ㅋㅋㅋㅋ
근데 진짜 고객문의 깃에 올려주시면 안될까요 고객님?
아무튼 4년간 묵혀왔던 답답한 업무 병목을 해낸 테크티컬 라이터로서의 첫 업무! 만족도 100점!!
워드를 웹 문서로 전환하거나 형상 관리 도입을 고민하고 계신 분들께 이 글이 많은 도움이 되었으면 좋겠습니다.