Readme에서 VitePress로 가이드 문서 이사하기 w/ Notion, Gitbook

셀렉트는 가이드 문서가 중요한 서비스이다보니 계속해서 더 나은 방향으로 가고자 하고 있습니다.

이번에 가이드 문서를 리드미(readme.com)라는 서비스에서 VitePress로 이전하였는데요. 장단점 그리고 이전과정에서 겪은 경험들과 개인적으로 느낀점을 글로 풀어보았습니다.

과거에 노션Notion, 깃북Gitbook을 거쳐 리드미로 이전하였으며 당시의 판단 기준도 함께 공유해보겠습니다.

참고로 VitePress는 리드미와 같이 SaaS 제품이 아니고 Static Site Generator이며 비슷한 프로젝트인 Docusaurus와 VuePress 등 다른 방법들도 함께 비교하다 VitePress를 선택하게 되었습니다.

리드미readme에서 이사한 이유

사실 리드미는 충분히 좋은 서비스였습니다. 사용하다보니 몇가지 아쉬운 점이 있었는데요. 크게 검색, 로딩속도, 편집기 세 가지 부분에서 개선이 필요하다고 느꼈습니다.

검색

리드미는 검색시 최대한 많은 내용이 나오는 구조이고 검색결과를 컨트롤하는 기능이 따로 없었습니다. 검색결과를 한눈에 파악하고 필요한 페이지로 이동하는데 어려움이 있다고 판단했습니다.

로딩 속도

일반적인 사이트를 생각하면 리드미로 만든 페이지에 접속하거나 편집 화면에 들어갈때 속도가 많이 느린것은 아니었습니다. 

하지만 가이드 문서 특성상 홈페이지와 다르게 빠르게 방법을 찾아야하고 자주 보게되는 페이지이기 때문에 페이지 이동이나 검색 결과가 나오는데 더 빨라야한다고 생각했습니다.

그리고 Vitepress와 같은 Static Site Generator는 매우 빠른 로딩속도를 보여주었습니다.

편집기

가이드 문서를 리드미로 이전할 당시 2022년 10월경 깃북(GitBook)의 편집기와 비교를 하였습니다.

깃북의 편집기는 한글을 타이핑했을 때 반복적으로 같은 내용이 적히거나 수정시 문제가 자주 발생하는 편이었습니다. 현재 2023년 10월 다시 확인해보니 많이 개선된 것으로 보이네요. 리드미는 이런 한글 문제는 없었습니다.

다만 내용이 많아져서인지 리드미의 편집기가 새롭게 업데이트가 된 다음부터 꽤 긴기간동안 몇가지 버그가 계속되었습니다.

이사 과정

문서 내용이 많다보니 이사를 얼마나 쉽게할 수 있느냐도 고민사항이었는데요.

내용

깃북에서 리드미로 이사할때 결정적인 이유중 하나가 내용을 한꺼번에 복사하거나 내보내기가 어려웠다는 점이었습니다.

하지만 리드미는 마크다운Markdown 기반으로 작성할 수도 있고 GUI 편집기와 Raw mode(마크다운 작성모드)를 자유롭게 전환할 수 있어 나중에 붙여넣기나 복사, 내보내기가 쉽다고 판단했습니다.

Vitepress 또한 마크다운 기반으로 내용을 작성하기 때문에 90% 이상의 내용은 복사, 붙여넣기로 쉽게 이전이 가능했습니다.

Vitepress로 옮길 때는 개발자가 폴더와 마크다운 파일(.md)을 먼저 정리하고 내용을 함께 옮겼습니다. 

경로

리드미에서 잘 관리되지 않던 경로를 이번기회에 정리하였습니다. 특히 한글 경로는 링크를 공유했을 때 너무 긴 링크가 될 때가 있어 지저분하거나 어떤 페이지인지 유추할 수가 없었습니다. 

이번에 셀렉트 가이드는 Vercel로 배포하여 vercel.json 파일에 리다이렉트redirect 설정을 입력하여 배포할때마다 반영되게하였습니다.

이미지

리드미는 SaaS 제품이기 때문에 이미지를 바로 업로드하면 자체 스토리지에 저장을 시켜주었는데요.

Vitepress는 셀렉트 팀에서 직접 호스팅해야하기 때문에 이미지를 어떻게 관리할지도 판단해야했습니다.

최소한의 리소스와 함께 지속적으로 쓰기 좋은 서비스를 찾아보았는데요. 셀렉트 팀에서 사용하는 노션Notion이나 Umso라는 웹사이트 빌더 서비스에 이미지 파일을 관리할지 고민하다가 Cloudflare에서 제공하는 Cloudflare Images 서비스를 발견하였습니다.

오버스펙이라는 고민이 있었지만 Cloudflare Images 덕분에 셀렉트 팀에서 필요한 수준은 저렴한 비용으로 고객들이 이미지를 빠르게 볼 수 있게 되었습니다.

Vitepress 사용 후기

8월 20일 세팅을 시작한 다음부터 하루 이틀안에 마무리하였고 한달 넘게 사용하였습니다.

결론부터 말씀드리면 매우 만족하고 있습니다. 

가장 와닿는 장점은 배포하기 전에 수정하는 내용 전후를 비교하기가 쉽다는 것입니다. 개발자분들은 너무나도 익숙한 경험이지만 비개발자 입장에서 리드미의 아쉬웠던 점을 확실하게 긁어주었습니다. 

Vitepress는 개발자가 아니어도 가능하다고 생각합니다. 물론 공부가 필요하겠지만요. "개발자가 아닌 사람도 내용을 편집할 수 있는가?"라는 기준은 GitHub의 코드스페이스 기능을 활용하였습니다. 개발 편집기에 익숙해진다면 어렵지 않습니다.

특히 Github의 Codespaces를 활용해서 dev 환경에 배포해 실제 느낌을 바로바로 직접볼 수 있습니다.

내용을 찾거나 복사하기가 쉬워졌고 최근에 어떤 내용을 업데이트했는지 바로 확인할 수 있습니다.

단점은 파일을 만들면 다른 작업을 하기 어렵다는점이었는데요. commit을 자주하라는 피드백 받고나서 편리해졌습니다.

알골리아Algolia를 설치해서 쓸 수 있었다는 점도 소소한 장점이었습니다.

리드미, 깃북 후기

Vitepress로 이전하기 전후로 기존에 사용했던 서비스들을 다시한번 검토해보았습니다.

깃북은 무료 플랜이 있고 다시 접속해도 편집이 가능했지만 리드미readme는 유료 플랜만 있기 때문에 결제를 중지한 다음부터는 편집자체가 막혔습니다.

다행히 두 서비스 모두 결과페이지를 방문할 수는 있습니다.

깃북은 기능추가와 더불어 변경시 이름을 더 적극적으로 적게하는등 Github과 연계된 모습을 좀더 보여주고 있었습니다. 다만 여전히 Markdown Raw mode가 없고 Export가 아쉽습니다.

리드미는 아무래도 기반이 API Reference 문서를 만들어주는데서 시작했다보니 요금정책도 따라간듯합니다.

결론 & 비교표

주요 부분을 비교표로 만들어보았습니다.

셀렉트의 경우 YAML, SQL, API 등의 정보를 잘 담고 검색이 빨라야한다고 생각했으며 변경사항 확인도 중요하다고 판단해서 Vitepress에 더 끌렸습니다만, 각 서비스나 방법 모두 각자의 장점이 있고 Vitepress의 아쉬운점도 분명히 있습니다.

추가로 Vitepress나 여러 가이드문서 서비스에 대해 궁금한점이 있다면 편하게 연락해주세요.

과거 가이드들은 아래 링크에서 확인해보실 수 있어요.

• 노션: https://ysgteam.notion.site/4e11196842c941aaab817d57006041f3
• 깃북: https://select.gitbook.io/docs/
• 리드미: https://select.readme.io/docs (참고: 무료 플랜에서는 가이드 기능을 쓸 수 없습니다. 퍼블릭하게 접근이 불가능해지며, 로그인하여 볼 수 있지만 내용을 수정할 수는 없습니다.)
• Vitepress: https://docs.selectfromuser.com/

가이드 문서를 만들일이 있을때 참고가 되시면 좋겠습니다.

감사합니다.