Docs as Code: API 문서화를 코드처럼 관리하는 방법

programming/tips

jamie91 2025. 3. 1. 18:19

API 레퍼런스가 필요한 이유

SIGDOC에서 개발자가 새로운 API를 마주했을 때 어떤 행동을 하는지를 주제로 실험을 해 본 결과 API 레퍼런스에 2번째로 가장 많이 시간을 할애한다고 합니다.

Docs as code는 기술 문서를 소스 코드처럼 취급하고 관리하는 접근법입니다.
Docs like Code로도 불립니다.
Docs as Code는 소프트웨어 개발 방식과 유사하게 코드의 형태로 문서를 작성하고, 해당 파일을 빌드하고, 테스트를 진행한 후, 결과물을 배포할 수 있도록 합니다.
또한 CI/CD, 컨테이너 등과 같은 도구를 사용함으로써 문서의 오류 판독, 관리 단계를 자동화 할 수 있으며, 서비스의 안정성을 제공할 수 있습니다.

최근 다양한 조직에서 Agile 방법론을 도입함에 따라 서비스의 개발 속도, 업데이트 주기가 빨라지게 되었으며, 문서 작성자는 서비스의 어떤 점이 개선되고, 추가되었는지 등 서비스에 대한 최신 정보를 사용자에게 제공할 수 있어야 합니다.
Docs as Code는 문서를 코드처럼 관리함으로써 팀의 협업과 생산성을 증가시킬 수 있습니다.
문서를 GitHub, GitLab 등에 관리함으로써 문서에 대한 변경 내역(수정 날짜, 수정자, 변경된 내용)을 누구나 확인할 수 있으며, 문서 작성에 대한 규칙을 정함으로써 변경되는 내용에 대해 팀원, 개발자들과 함께 리뷰할 수 있습니다.
코드처럼 작성이 되기 때문에 프레임워크와 같은 일관된 구조를 사용하여 생산성과 효율성을 높일 수 있습니다.
테스트와 배포 환경에서도 오탈자와 같은 부분을 자동으로 검사할 수 있으며, 작은 수정이라도 해당 업데이트에 대한 문서 배포가 가능합니다.
특히 컨테이너와 같은 다양한 소프트웨어 환경과 함께 사용할 경우 배포 버전에 문제가 생겨도, 이전 특정 버전으로 빠른 수정이 가능합니다.
기술의 정확성과 일관성에 가치를 둘 수 있습니다.
자동화를 통해 콘텐츠 개발에 더 집중할 수 있습니다.

정적 파일 생성: SSG는 템플릿 엔진과 마크다운과 같은 마크업 언어를 사용하여 소스 코드를 처리하고 정적 HTML 파일로 변환합니다. 이러한 파일은 서버 측에서 동적으로 생성되지 않으며, 사전에 생성되어 웹 서버에 배포됩니다.
간단한 구조: 대부분의 SSG는 간단하고 직관적인 디렉토리 구조를 가지고 있습니다. 일반적으로 소스 코드 및 템플릿 파일은 별도의 디렉토리에 저장되며, 변환된 정적 파일은 또 다른 디렉토리에 저장됩니다.
자동화된 빌드 프로세스: SSG는 소스 코드를 컴파일하고 정적 파일을 생성하는 자동화된 빌드 프로세스를 제공합니다. 개발자는 명령어를 실행하여 소스 코드를 빌드하고 웹 사이트를 생성할 수 있습니다.
편리한 개발 환경: SSG는 개발자가 템플릿 엔진, 마크다운, CSS 전처리기 등과 같은 다양한 도구를 사용하여 웹 사이트를 개발할 수 있는 편리한 환경을 제공합니다.
속도 및 보안 향상: 정적 사이트는 동적인 사이트보다 빠르며, 보안에도 더 강력합니다. 정적 파일은 캐시되기 쉽고, 웹 서버에서 쉽게 제공될 수 있어 성능과 보안을 향상시킵니다.

728x90