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

API 레퍼런스가 필요한 이유

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

 

API 레퍼런스 자동화 기술

• Swagger
• Javadoc
• AsciiDoc
• GoDoc

 

 

 

 

 

자동화 기술을 사용하지 않는 이유

 

Feedbacks

• API 수정할 때마다 컨플문서 수정하기 너무 힘듭니다..
• 문서는 문서대로 테스트는 포스트맨.. 관리 포인트 너무 많아..
• 문서가 너무 무겁.. 경량화 혹은 분할 필요.
• 스웨거, Asciidoc, 컨플루언스.. 통일화 필요! 

 

SSG을 통한 Docs as code

정의

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

필요성

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

 

Static-Site Generator

정의

• SSG는 웹 사이트를 생성하는 데 사용되는 도구입니다.
• 정적 사이트 생성기는 동적인 콘텐츠가 없는 웹 사이트를 만들기 위해 사용됩니다.
• 웹 개발자들에게 효율적이고 편리한 방법으로 정적 웹 사이트를 만들 수 있는 기능을 제공합니다.

특징

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

 

SSG 비교 분석

 

 

References

• https://techblog.lycorp.co.jp/ko/docusaurus-as-a-technical-document-website
• https://engineering.linecorp.com/ko/blog/document-engineering-api-documentation
• https://medium.com/@Danpatpang/docs-as-code-298802a691d1
• https://koko8829.tistory.com/2097
• https://sigdoc.acm.org/cdq/how-developers-use-api-documentation-an-observation-study/
• https://toss.tech/article/docs-engineering