문서화가 중요한 이유
좋은 문서는 팀의 생산성을 높이고 온보딩을 쉽게 합니다. 40년간 문서화의 가치를 경험해온 저로서는 '문서화되지 않은 것은 존재하지 않는 것'이라고 말씀드립니다. 코드는 '무엇을' 하는지 보여주지만, '왜'와 '어떻게 사용하는지'는 문서가 필요합니다.
어떤 문서를 작성할까
README: 프로젝트 개요, 설치, 빠른 시작 가이드. API 문서: 엔드포인트, 요청/응답 형식, 예제. 아키텍처 문서: 시스템 구조, 설계 결정, 다이어그램. 개발 가이드: 환경 설정, 코딩 컨벤션, 배포 절차. ADR(Architecture Decision Record): 중요한 결정과 이유.
좋은 문서 작성법
독자를 생각합니다. 누가 읽을지에 따라 내용이 달라집니다. 간결하게 작성합니다. 필요한 정보만 담습니다. 예제를 포함합니다. 코드 예제는 백 마디 설명보다 낫습니다. 최신 상태를 유지합니다. 오래된 문서는 혼란을 줍니다. 버전 관리합니다. 문서도 코드처럼 Git으로 관리합니다.
자동 생성 문서
코드에서 문서를 자동 생성하면 동기화가 쉽습니다. JSDoc, Sphinx, Javadoc이 API 문서를 생성합니다. OpenAPI(Swagger)는 API 명세서와 UI를 생성합니다. Storybook은 UI 컴포넌트 문서화에 유용합니다. 하지만 자동 생성만으로는 부족합니다. 개념 설명, 튜토리얼은 수동으로 작성해야 합니다.
문서화 문화 만들기
문서 작성을 개발 프로세스에 포함합니다. PR에 문서 업데이트를 요구합니다. 문서 리뷰도 코드 리뷰처럼 합니다. 문서화를 인정하고 보상합니다. 완벽할 필요 없습니다. 조금이라도 있는 게 없는 것보다 낫습니다. 점진적으로 개선합니다.
댓글
0