개발자 입장에서 사용할 만한 문서화 도구들을 정리합니다.
직접 배포
직접 코드로 사이트를 작성하고, GitHub Pages나 Vercel 등으로 배포할 수 있습니다.
Docusaurus
- Meta 팀의 오픈소스 프로젝트로, 지속적으로 관리되고 있습니다.
- React 기반입니다.
- 깊게 파고들기 위해 프론트엔드 지식이 필요할 수 있습니다.
- 개인적으로 디자인이 가장 화려합니다.
- 다양한 기능을 필요로 할 때 강력한 성능을 발휘합니다.
- 특히 MDX와 다국어를 적용할 때 가장 편했습니다.
React Native 등 Meta의 여러 프로젝트 문서와 다수의 오픈소스에서 활용하고 있습니다.
MkDocs
- Python 환경을 기반으로 사이트를 생성합니다.
- 디자인은 평범하지만, 깔끔합니다.
- 설정을 빠르고 간단하게 할 수 있는 것이 큰 장점입니다.
- 대부분 원본에서 파생된 Material for MkDocs를 많이 사용합니다.
대표적으로 Argo 프로젝트에서 사용하고 있습니다.
기타 사이트 생성기
Hugo, Astro 등의 다른 도구 + 템플릿으로도 문서를 작성할 수 있습니다.
보통 개발 블로그로 검색했을 때 언급되는 도구는 대부분 활용 가능합니다.
외부 서비스
- 조직 단위에서 사용할 경우 Notion이 대표적이고, Confluence도 사용합니다.
- 개인의 경우 GitBook 활용 사례도 많았습니다.
- 문서를 작성하고 배포하는 작업이 매우 간편합니다.
- Git과 연동하여 따로 백업도 가능합니다.
- 다만, 한글로 문서 작업 시 타이핑 오류가 있습니다.
실제 2024년 상반기에 사용 시에도 해당 이슈가 있었습니다.
내용을 지우고 다시 작성하거나, 붙여 넣기로 해결 가능하지만 불편한 요소입니다.
기타
현재 Obsidian으로 작성된 이 페이지는 GitLab Pages로 배포되고 있습니다.
기존에는 MkDocs를 사용했지만, 현시점에서는 Quartz를 더 추천합니다.