Docusaurus

Docusaurus란 무엇인가

Docusaurus(github.com/facebook/docusaurus)는 스스로를 오픈소스 프로젝트 웹사이트를 쉽게 만들고 배포하고 유지하기 위한 프로젝트라고 소개합니다. 실제로는 문서를 일등 시민으로 다루는 React 기반 정적 사이트 생성기입니다. npm init docusaurus@latest 명령 하나로 문서 영역과 블로그, 단독 페이지, 테마가 이미 갖춰진 사이트가 나오므로, 첫날은 기술 구성을 짜맞추는 대신 내용을 쓰는 데 쓸 수 있습니다. Meta가 이를 공개한 이유는 사내에서 운영하는 수많은 오픈소스 프로젝트를 감당하는 데 도움이 되기 때문이라고 밝히고 있습니다. 코드는 MIT 라이선스이며, 저장소 안의 문서 본문에는 별도의 Creative Commons 라이선스가 붙습니다.

• 콘텐츠 종류마다 별도의 플러그인 — 저장소는 문서용, 블로그용, 단독 페이지용 공식 패키지를 각각 따로 제공합니다. 그래서 문서만 있는 사이트, 문서와 변경 이력, 또는 마케팅 홈까지 포함한 완전한 사이트를 두 번째 도구 없이 구성할 수 있습니다.
• 보통은 따로 붙이는 조각들이 이미 들어 있다 — 사이트맵 생성, Algolia 기반 검색, 옮긴 URL을 위한 클라이언트 리디렉션, 번역, PWA 지원, Mermaid 다이어그램, 이미지 최적화, 구글 애널리틱스 태그가 모두 같은 저장소 안에서 관리되는 패키지로 존재합니다.
• 집필 형식은 MDX — 페이지는 React 컴포넌트를 넣을 수 있는 마크다운입니다. 그래서 그 외에는 저장소의 파일 하나일 뿐인 페이지 안에 실행되는 코드 블록이나 상호작용 예제를 둘 수 있습니다.

문서, 블로그, 마케팅 페이지는 서로 다른 일이다

문서 사이트를 낭비하는 가장 흔한 방법은 그것을 그저 또 하나의 콘텐츠 표면으로 취급하고 전부를 같은 숫자로 평가하는 것입니다. 이 세 표면은 서로 다른 상태로 도착하는 서로 다른 사람을 끌어옵니다. 그리고 그중 당신을 한 번도 들어본 적 없는 사람에게 발견되려 애쓰는 것은 하나뿐입니다.

Docusaurus는 셋 다 기꺼이 담아 줍니다. 그게 함정입니다. 한 빌드에서 함께 나오다 보니 하나로 묶여 평가됩니다. 다른 무엇보다 먼저 보고서를 분리하세요. 문서 페이지와 랜딩 페이지는 트래픽 표에서 똑같아 보이지만 완전히 다른 질문에 답하고 있습니다. 퍼블리싱 쪽이 진짜 일이라면 Ghost가 그 용도로 만들어졌고, 풀 리퀘스트를 열지 않는 사람을 위한 편집 화면이 필요하다면 그건 Payload입니다.

문서 사이트는 성장 스택의 어디에 놓이는가

문서는 대부분의 개발자 도구가 보유한 콘텐츠 가운데 의도가 가장 강하면서도 가장 꾸준히 투자가 모자란 영역입니다. 특정한 종류의 검색어에서는 순위도 잡습니다. 개발자는 오류 메시지, API와 함수 이름, 그리고 이 도구에서 이걸 어떻게 하느냐는 식의 문장을 검색합니다. 경쟁이 옅고 의도가 강한 검색어들이라, 정확한 답만 있으면 경쟁 심한 대표 키워드에 드는 노력 없이 가져올 수 있습니다. 진짜 유입 표면이지만 폭은 좁습니다. 그런 검색어 대부분에 이미 당신 제품의 이름이거나 당신 제품이 만든 문제가 들어 있기 때문입니다. 문서는 이미 가진 것을 키우지, 처음부터 만들어 내지는 않습니다. 관심을 먼저 얻는 문제는 개발자 도구를 어떻게 마케팅하나에서, 페이지가 아니라 주제를 소유하는 이야기는 토픽 권위에서 다룹니다.

AgentCeres — agentceres.com의 AI Growth Officer — 를 만들며 얻은 일차 경험입니다. 예상하지 못한 것은 문서 페이지와 마케팅 페이지가 분석 보고서에서는 똑같아 보이면서 정반대의 일을 한다는 점이었습니다. 하나는 결정 중인 사람이 읽고, 다른 하나는 이미 결정했지만 지금 막힌 사람이 읽습니다. 알아차린 계기는 우리 제품의 채팅으로 들어오는 질문들이 거의 한 줄씩 우리 문서에 있었어야 할 제목과 겹친다는 사실이었습니다. 지원 스레드는 어떤 키워드 도구보다 나은 목차가 됩니다. 제품이 더 이상 자명하지 않게 되는 정확한 지점들이, 사람들이 부딪히는 빈도순으로 정렬된 목록이기 때문입니다. 이번 주에 Docusaurus를 설치한다면, 가장 먼저 쓸 가장 값진 페이지는 기능 소개가 아닙니다. 이미 손으로 세 번 타이핑한 그 질문에 대한 답입니다.