코드형 문서란? 코드 문서 작성 방법 (최고의 방법)

button

"코드로서의 문서(Docs as Code)"란 무엇인가?

끊임없이 발전하는 소프트웨어 개발 환경에서 명확하고 간결하며 유지보수 가능한 문서의 중요성은 아무리 강조해도 지나치지 않습니다. 전통적으로 문서는 종종 코드베이스와 별도로 생성 및 관리되어 구식이고 부정확하며 궁극적으로는 도움이 되지 않는 리소스로 이어졌습니다. 그러나 "코드로서의 문서(Docs as Code)" 철학에 의해 주도되는 패러다임의 변화가 진행 중입니다. 이 접근 방식은 문서 작성을 소프트웨어 코드와 동일한 엄격함과 프로세스로 취급하여 기술 정보가 생성, 관리 및 소비되는 방식을 혁신할 것을 주장합니다.

이 글은 Docs as Code의 핵심 개념을 깊이 탐구하고 그 이점과 일반적인 워크플로우를 살펴봅니다. 또한 효과적인 코드 문서 작성에 대한 포괄적인 가이드를 제공하며, 다양한 대상에게 명확성, 유지보수성 및 유용성을 보장하는 모범 사례를 설명합니다.

Docs as Code의 핵심 원칙

본질적으로 "Docs as Code"는 소프트웨어 개발 원칙, 관행 및 도구를 문서 생성 및 유지보수에 적용하는 접근 방식입니다. 전통적인 워드 프로세서나 독점 문서 소프트웨어를 사용하는 대신, Docs as Code는 일반적으로 코딩과 관련된 일반 텍스트 마크업 언어, 버전 관리 시스템, 자동화된 빌드 프로세스 및 협업 워크플로우를 활용합니다.

이 철학을 뒷받침하는 핵심 원칙은 다음과 같습니다.

• 일반 텍스트 형식: 문서는 Markdown, reStructuredText 또는 AsciiDoc와 같은 경량 마크업 언어로 작성됩니다. 이러한 형식은 사람이 읽기 쉽고 배우기 쉬우며 다양한 출력 형식(HTML, PDF 등)으로 쉽게 변환될 수 있습니다.
• 버전 관리 시스템(VCS): 문서 파일은 VCS, 가장 일반적으로 Git에 저장 및 관리됩니다. 이를 통해 변경 사항 추적, 새로운 기능 또는 주요 문서 개편을 위한 브랜치 생성, 기여 병합, 필요한 경우 이전 버전으로 되돌리기가 가능합니다. 코드와 마찬가지로 문서에 대한 모든 수정 사항이 기록되어 명확한 감사 추적을 제공합니다.
• 협업: GitHub, GitLab 또는 Bitbucket과 같은 VCS 플랫폼을 사용함으로써 문서는 협업 작업이 됩니다. 개발자, 기술 문서 작성자 및 사용자까지도 풀 리퀘스트(또는 머지 리퀘스트)와 같은 익숙한 메커니즘을 통해 기여, 검토 및 변경 제안을 할 수 있습니다.
• 자동화: 코드를 컴파일하는 데 사용되는 것과 유사한 빌드 프로세스는 일반 텍스트 소스 파일을 게시 가능한 문서로 변환하는 데 사용됩니다. 여기에는 스타일 일관성을 위한 린팅, 링크 유효성 검사, 웹 서버 또는 기타 배포 채널로의 문서 배포가 포함될 수 있습니다. CI/CD(지속적 통합/지속적 배포) 파이프라인은 변경 사항이 저장소에 푸시될 때마다 이러한 작업을 자동화할 수 있습니다.
• 단일 정보 출처: 문서는 설명하는 코드와 함께, 종종 동일한 저장소 내에 위치합니다. 이러한 공동 배치는 개발자가 코드를 수정할 때 문서를 쉽게 업데이트할 수 있도록 하여 소프트웨어와 지원 정보 간의 불일치 가능성을 줄입니다.
• 검토 및 테스트: 문서 변경 사항은 코드 검토와 유사한 검토 프로세스를 거칩니다. 이는 정확성, 명확성 및 일관성을 보장합니다. 자동화된 검사(예: 깨진 링크 또는 문법 검사)도 워크플로우에 통합될 수 있습니다.

Docs as Code 도입의 이점

Docs as Code 모델로 전환하는 것은 개발팀과 조직에 다양한 이점을 제공합니다.

• 향상된 정확성 및 최신 정보: 문서는 코드와 함께 관리되고 동일한 워크플로우를 사용하여 업데이트되기 때문에 소프트웨어의 현재 상태를 훨씬 더 잘 반영할 가능성이 높습니다. 기능이 변경되면 관련 문서는 동일한 커밋 또는 풀 리퀘스트에서 업데이트될 수 있습니다.
• 향상된 협업: 개발자는 이미 버전 관리 및 협업 코딩 플랫폼에 익숙합니다. 이를 문서에 적용하면 기여 장벽이 낮아집니다. 기술 문서 작성자와 개발자는 더욱 원활하게 협력할 수 있습니다.
• 더 나은 버전 관리 및 기록: 문서에 대한 모든 변경 사항이 추적되어 누가, 언제, 왜 변경했는지 쉽게 확인할 수 있습니다. 이는 문서의 진화를 이해하고 필요한 경우 이전 상태로 되돌리는 데 매우 유용합니다.
• 향상된 효율성 및 자동화: 자동화된 빌드 및 배포 프로세스는 수동 문서 업데이트에 비해 상당한 시간과 노력을 절약합니다. CI/CD 파이프라인은 항상 최신 문서를 사용할 수 있도록 보장합니다.
• 스타일 및 형식의 일관성: 린터 및 스타일 검사기를 빌드 프로세스에 통합하여 모든 문서에서 일관된 형식 및 작성 스타일을 적용할 수 있습니다.
• 개발자 역량 강화: 문서에 쉽게 기여하고 업데이트할 수 있을 때 개발자는 문서에 대한 소유권을 가질 가능성이 높습니다. 이는 더 포괄적이고 개발자 친화적인 문서로 이어집니다.
• 비용 절감: 오픈 소스 도구 및 익숙한 워크플로우를 활용함으로써 조직은 독점 문서 소프트웨어 및 전문 교육과 관련된 비용을 잠재적으로 절감할 수 있습니다.
• 완료 정의의 일부로서의 문서: 문서 업데이트를 개발 라이프사이클에 통합하는 것은 기능이 관련 문서도 완료 및 검토될 때까지 "완료"로 간주되지 않음을 의미합니다.

일반적인 Docs as Code 워크플로우

일반적인 Docs as Code 워크플로우는 소프트웨어 개발 워크플로우를 반영하여 민첩성과 품질을 촉진합니다.

1. 생성 또는 편집: 작성자 또는 개발자는 일반 텍스트 편집기와 선택한 마크업 언어(예: Markdown)를 사용하여 새 문서 파일을 생성하거나 기존 파일을 편집합니다.
2. 변경 사항 커밋: 변경 사항은 수정을 설명하는 설명적인 커밋 메시지와 함께 로컬 Git 저장소에 커밋됩니다.
3. 원격 저장소로 푸시: 로컬 커밋은 중앙 원격 저장소(예: GitHub, GitLab)로 푸시됩니다.
4. 풀/머지 리퀘스트 생성: 변경 사항이 중요하거나 동료 검토가 필요한 경우 풀 리퀘스트(또는 머지 리퀘스트)가 생성됩니다. 이는 공식적인 검토 프로세스를 시작합니다.
5. 검토 및 반복: 검토자는 제안된 문서 변경 사항을 검토하고, 피드백을 제공하고, 질문하고, 풀 리퀘스트 내에서 직접 개선 사항을 제안합니다. 작성자는 이 피드백을 해결하기 위해 추가 커밋을 할 수 있습니다.
6. 자동화된 검사(CI): CI(지속적 통합) 파이프라인은 문서에 대한 사전 정의된 검사를 자동으로 실행합니다. 여기에는 일관성을 적용하기 위한 링크 검사기, 스타일 린터 및 문서가 올바르게 생성될 수 있는지 확인하는 빌드 유효성 검사가 포함될 수 있습니다.
7. 병합: 변경 사항이 검토자에게 승인되고 모든 자동화된 검사를 통과하면 풀 리퀘스트가 주 문서 브랜치에 병합됩니다.
8. 빌드 및 배포(CD): CD(지속적 배포) 파이프라인은 소스 파일에서 최종 문서를 자동으로 빌드하고 지정된 플랫폼(예: 문서 웹사이트, PDF 생성기 또는 내부 지식 베이스)에 배포합니다.

Docs as Code 스택의 일반적인 도구

Docs as Code 생태계는 다양한 도구에 의존하며, 그 중 상당수는 오픈 소스이며 소프트웨어 개발에서 널리 채택되고 있습니다.

• 마크업 언어:
• Markdown: 단순성과 사용 편의성으로 인기가 높습니다.
• AsciiDoc: Markdown보다 기능이 풍부하며 복잡한 문서에 적합합니다.
• reStructuredText (reST): 종종 Sphinx와 함께 사용되며 기술 문서에 강력합니다.
• 버전 관리 시스템:
• Git: 사실상의 표준 버전 관리 시스템입니다.
• VCS 플랫폼 (호스팅 및 협업용):
• GitHub
• GitLab
• Bitbucket
• 정적 사이트 생성기 (SSG): 이 도구는 일반 텍스트 파일을 HTML 웹사이트로 변환합니다.
• Sphinx: Python 프로젝트에 탁월하며 reStructuredText를 광범위하게 지원합니다. 다양한 출력 형식을 생성할 수 있습니다.
• MkDocs: Markdown을 사용하는 빠르고 간단한 SSG입니다.
• Hugo: Go로 작성되었으며 놀라운 속도로 알려져 있습니다.
• Jekyll: Ruby 기반이며 GitHub Pages를 지원합니다.
• Docusaurus: Markdown 기반이며 Facebook에서 개발되었으며 버전 관리 및 번역 기능을 갖춘 문서 사이트에 최적화되어 있습니다.
• GitBook (명령줄 도구 또는 플랫폼): 자체 호스팅하거나 서비스로 사용할 수 있으며 사용자 친화적인 편집 경험을 제공합니다.
• 린터 및 스타일 검사기 (일관성 및 품질용):
• Vale: 산문을 위한 강력하고 구성 가능한 린터입니다.
• textlint: 텍스트 및 Markdown을 위한 플러그인 가능한 린팅 도구입니다.
• markdownlint: Markdown 파일의 스타일 및 구문 문제를 확인하는 데 특화되어 있습니다.
• CI/CD 도구 (자동화용):
• Jenkins
• GitLab CI/CD
• GitHub Actions
• CircleCI
• 텍스트 편집기/IDE (강력한 일반 텍스트 및 Git 지원):
• Visual Studio Code (VS Code)
• Sublime Text
• Atom
• Vim
• Emacs

코드 문서 작성 방법: 모범 사례

Docs as Code는 문서를 효율적으로 관리하기 위한 프레임워크를 제공하지만, 문서 자체의 내재적 품질은 작성 방식에 달려 있습니다. 효과적인 코드 문서는 명확하고 간결하며 정확하고 포괄적이며 대상 독자를 세심하게 겨냥해야 합니다. 모범 사례를 준수하면 문서가 목적을 효과적으로 달성할 수 있습니다.

1. 독자 파악

문서를 작성하기 전에 누가 문서를 읽을 것인지 파악하는 것이 중요합니다. 다른 독자는 기술 전문 지식 수준이 다르며 고유한 요구 사항을 가지고 있습니다. 그에 따라 콘텐츠를 맞춤화하는 것이 가장 중요합니다.

일반적인 독자는 다음과 같습니다.

• 새로운 개발자/팀원: 이들은 신속하게 업무에 적응하기 위해 상위 수준 개요, 포괄적인 설정 가이드 및 입문 튜토리얼이 필요합니다.
• 숙련된 개발자 (팀 내): 일반적으로 상세한 API 참조, 심층적인 아키텍처 다이어그램, 복잡한 로직 또는 명확하지 않은 구현에 대한 설명이 필요합니다.
• 코드를 통합하는 개발자 (예: API 소비자): 이 그룹은 명확한 사용 예제, 명확한 인증 및 권한 부여 가이드, 엔드포인트, 요청/응답 형식 및 오류 코드를 포함하는 강력한 API 문서가 필요합니다.
• 미래의 당신: 가장 중요하지만 종종 간과되는 독자 중 하나는 미래의 자신입니다. 자세한 문서는 오랜 공백 후에 코드를 다시 검토할 때 상당한 시간과 노력을 절약할 수 있습니다.
• 테스터/QA 팀: 효과적인 테스트를 설계하기 위해 의도된 기능, 예상되는 입력 및 출력, 경계 조건 및 잠재적인 엣지 케이스를 이해해야 합니다.
• 최종 사용자 (사용자 대상 문서용): 이 독자는 소프트웨어 기능 사용 방법에 대한 명확하고 비기술적인 설명이 필요합니다. (이 글은 코드 문서에 중점을 두지만, Docs as Code 원칙은 여기에 확장될 수 있습니다).

각 문서에 대해 대상 독자에게 적합하도록 언어, 세부 수준 및 제공되는 예제 유형을 항상 조정하십시오.

2. 올바른 문서 유형 선택

포괄적인 소프트웨어 프로젝트에는 각기 다른 목적을 가진 다양한 문서 유형이 필요합니다. 전달해야 하는 정보에 적합한 형식을 선택하는 것이 중요합니다.

강력한 문서 스위트에는 다음이 포함될 수 있습니다.

• 코드 내 주석:
• 목적: 특정 코드 조각 뒤에 있는 이유를 설명하고, 복잡한 알고리즘을 명확히 하며, 명확하지 않은 로직을 강조하거나 잠재적인 위험을 경고하기 위함입니다. 코드가 자명하다면 코드가 하는 일을 단순히 반복해서는 안 됩니다.
• 모범 사례: 주석을 간결하고 핵심적으로 유지하십시오. 코드를 작성할 때 동시에 작성하십시오. 코드의 문자 그대로의 번역이 아닌 근거와 의도에 집중하십시오. 결정적으로, 잘못된 정보를 방지하기 위해 기본 코드가 변경될 때마다 주석을 항상 업데이트하십시오.
• README 파일:
• 목적: 프로젝트, 특정 모듈, 마이크로서비스 또는 코드베이스 내의 디렉토리에 대한 상위 수준 개요를 제공하기 위함입니다. 종종 코드를 탐색하는 사람의 첫 번째 진입점입니다.
• 모범 사례: 좋은 README는 간략한 프로젝트 설명, 전제 조건, 빌드 및 설치 지침, 기본 사용 예제, 기여 가이드라인 및 더 자세한 문서에 대한 링크를 포함합니다. 정보가 풍부하면서도 비교적 짧아야 합니다.
• API 문서:
• 목적: 클래스, 메서드, 함수 및 HTTP 엔드포인트를 포함하여 공개 API(Application Programming Interfaces)와 상호 작용하는 방법을 설명하기 위함입니다. 이는 라이브러리, 프레임워크, 마이크로서비스 및 외부에서 사용할 수 있는 모든 서비스에 필수적입니다.
• 모범 사례: 각 API 요소(예: 함수, 엔드포인트)에 대해 목적, 매개변수(이름, 데이터 유형, 설명, 필수 여부, 기본값), 반환 값(데이터 유형, 설명, 구조), 잠재적인 오류 또는 예외, 명확하고 실용적인 사용 예제를 꼼꼼하게 문서화하십시오. REST API용 Swagger/OpenAPI 또는 코드 라이브러리용 Javadoc/DocC/Sphinx autodoc과 같은 도구는 소스 코드 주석에서 이 문서 생성을 자동화할 수 있습니다.
• 튜토리얼 및 How-To 가이드:
• 목적: 튜토리얼은 학습 지향적이며 사용자가 특정 결과(예: "X 시작하기")를 달성하기 위한 일련의 단계를 안내합니다. How-to 가이드는 문제 지향적이며 특정 작업 또는 과제(예: "Z를 위해 Y를 구성하는 방법")에 대한 해결책을 제공합니다.
• 모범 사례: 복잡한 작업을 관리하기 쉽고 순차적인 단계로 나누십시오. 실행 가능한 코드 스니펫을 포함하고 예상되는 출력을 명확하게 보여주십시오. 잘 정의된 목표로 시작하십시오.
• 설명 문서 (개념):
• 목적: 상위 수준 개념, 시스템 아키텍처, 설계 결정, 데이터 모델 및 소프트웨어의 기본 원칙을 설명하기 위함입니다. 이 유형의 문서는 개발자가 "큰 그림"과 특정 구성 요소가 작동하는 컨텍스트를 이해하는 데 도움이 됩니다.
• 모범 사례: 복잡한 관계를 설명하기 위해 다이어그램(예: 아키텍처 다이어그램, 시퀀스 다이어그램)을 활용하십시오. 모든 전문 용어를 명확하게 정의하십시오. 중요한 설계 결정 뒤에 있는 근거와 고려된 절충안을 설명하십시오.
• 문제 해결 가이드:
• 목적: 사용자 및 개발자가 일반적인 문제, 오류 또는 예상치 못한 동작을 진단하고 해결하는 데 도움을 주기 위함입니다.
• 모범 사례: 자주 발생하는 문제, 잠재적인 근본 원인을 나열하고 명확하고 단계별 해결책 또는 해결 방법을 제공하십시오.
• 변경 로그/릴리스 노트:
• 목적: 새로운 기능, 버그 수정, 성능 개선 및 중요한 변경 사항을 포함하여 소프트웨어의 각 릴리스된 버전에서 이루어진 특정 변경 사항을 문서화하기 위함입니다.
• 모범 사례: 명확하고 일관된 형식을 유지하십시오. 변경 사항을 분류하십시오(예: 추가됨, 변경됨, 수정됨, 제거됨, 사용 중단). 업그레이드하는 사용자에게 경고하기 위해 중요한 변경 사항을 눈에 띄게 강조하십시오.

3. 명확하고 간결하게 작성

명확성과 간결성은 효과적인 문서의 초석입니다. 모호하거나 너무 장황한 텍스트는 도움이 되기보다는 혼란을 야기할 수 있습니다.

• 간단한 언어 사용: 불필요한 전문 용어와 약어를 피하십시오. 기술 용어가 필수적이라면 처음 사용할 때 명확하게 정의하십시오. 직접적인 표현을 위해 수동태(예: "함수에 의해 목록이 반환됩니다")보다 능동태(예: "함수는 목록을 반환합니다")를 선호하십시오.
• 구체적이고 명확하게 작성: 모호한 진술은 오해를 초래합니다. 구체적인 세부 사항, 매개변수 및 예상 결과를 제공하십시오.
• 짧은 문장과 단락 사용: 이는 특히 복잡한 기술 주제에 대해 텍스트를 더 쉽게 스캔하고 읽고 이해할 수 있도록 합니다. 긴 텍스트 블록을 나누십시오.
• 제목, 부제목 및 목록 사용: 제목(H2, H3 등)을 사용하여 문서를 논리적으로 구성하여 명확한 계층 구조를 만드십시오. 글머리 기호 및 번호 매기기 목록은 일련의 단계, 기능 또는 관련 항목을 제시하는 데 탁월합니다.
• 일관성 유지: 모든 문서에서 일관된 용어, 형식(예: 코드 스니펫, 메모, 경고), 어조를 사용하십시오. 스타일 가이드는 이를 달성하는 데 매우 유용할 수 있습니다.

4. 진행하면서 문서화 (또는 거의 동시에)

개발 주기 끝까지 문서 작성을 미루는 것은 흔한 함정입니다. 이는 종종 잊혀진 세부 사항, 부정확성 및 서두르고 불충분한 결과로 이어집니다.

• 문서를 워크플로우에 통합: 문서를 사후 고려 사항이 아닌 개발 프로세스의 필수적인 부분으로 취급하십시오. 스프린트 또는 개발 주기에 문서 작업을 포함하십시오. 새로운 기능, 버그 수정 또는 중요한 변경 사항에 대한 "완료 정의"의 일부로 업데이트된 문서를 만드십시오.
• 코딩 중에 주석 작성: 코드 조각의 목적, 복잡성 또는 특정 구현 뒤에 있는 이유를 설명하는 가장 좋은 시점은 코드가 머릿속에 생생할 때입니다.
• 설계 단계 초기에 API 문서 초안 작성: 구현 전 또는 구현 중에 API 문서의 예비 초안을 작성하는 것만으로도 인터페이스를 명확히 하고 잠재적인 문제를 식별하며 개발자를 위한 계약 역할을 할 수 있습니다.

5. 의미 있는 예제 제공

개발자에게 코드 예제는 종종 모든 문서에서 가장 가치 있는 부분입니다. 잘 만들어진 예제는 이해와 채택을 크게 가속화할 수 있습니다.

• 작동하는 코드 보장: 모든 코드 스니펫은 정확하고, 컨텍스트에서 이해하기에 충분히 완전하며, 가장 중요하게는 실제로 작동해야 합니다. 예제를 테스트하십시오.
• 실제 시나리오 설명: 코드가 해결하는 일반적인 사용 사례 및 실제 문제에 집중하십시오. 실용적인 가치를 제공하지 않는 지나치게 단순하거나 추상적인 예제는 피하십시오.
• 예제를 복사-붙여넣기 가능하게 만들기: 개발자가 최소한의 수정으로 자신의 프로젝트에 쉽게 복사하고 붙여넣을 수 있도록 코드 스니펫 형식을 지정하십시오.
• 예제 설명: 코드만 제공하지 마십시오. 예제가 무엇을 하는지, 왜 관련이 있는지 간략하게 설명하고 중요한 측면이나 구성을 강조하십시오.
• 예제 업데이트 유지: 이것은 아무리 강조해도 지나치지 않습니다. 기본 코드가 변경되면 사용법을 설명하는 예제도 업데이트해야 합니다. 구식 예제는 오해의 소지가 있고 실망스럽습니다.

6. 시각 자료 효과적으로 사용

다이어그램, 순서도, 스크린샷 및 기타 시각 자료는 종종 텍스트만으로는 복잡한 정보를 더 효과적이고 직관적으로 전달할 수 있습니다.

• 아키텍처 다이어그램: 시스템의 전체 구조, 구성 요소 및 상호 연결을 설명하는 데 사용하십시오.
• 순서도 및 시퀀스 다이어그램: 프로세스의 작업 순서 또는 다른 모듈 또는 서비스 간의 상호 작용을 보여주는 데 탁월합니다.
• 스크린샷 (UI 관련 문서용): 사용자 인터페이스 또는 그래픽 구성 요소가 있는 도구를 문서화할 때 주석이 달린 스크린샷은 사용자가 기능 및 탐색을 이해하는 데 크게 도움이 될 수 있습니다.
• 시각 자료를 단순하고 명확하게 유지: 혼란스럽거나 불필요한 세부 사항을 피하십시오. 다이어그램이 읽기 쉽고, 잘 레이블이 지정되어 있으며, 관련 텍스트를 지원하는지 확인하십시오. 시각 자산을 문서와 함께 저장하고(예: assets/images 폴더) 버전 관리를 하십시오.

7. 문서를 찾기 쉽게 만들기

아무리 완벽하게 작성된 문서라도 사용자가 필요할 때 찾을 수 없다면 쓸모가 없습니다.

• 중앙 집중식 위치: 모든 프로젝트 문서가 있는 명확하고 잘 알려져 있으며 쉽게 접근할 수 있는 장소(예: 전용 문서 웹사이트, 버전 관리 플랫폼의 섹션)를 설정하십시오.
• 검색 기능 구현: 대규모 문서 세트의 경우 강력한 검색 기능이 중요합니다. 사용자는 자신의 쿼리와 관련된 정보를 신속하게 찾을 수 있어야 합니다.
• 명확한 탐색 제공: 직관적인 메뉴, 포괄적인 목차 및 브레드크럼을 사용하여 사용자가 문서 내에서 방향을 잡고 탐색할 수 있도록 논리적인 구조를 사용하십시오.
• 광범위하게 (그리고 지능적으로) 링크: 관련 문서 페이지, API 참조 및 관련 섹션 간에 링크하십시오. 그러나 탐색하기 어려운 "웹"을 만드는 것에 주의하십시오. Docs as Code 도구는 종종 "링크 끊김"을 방지하기 위해 링크 유효성을 검사하는 데 도움이 될 수 있습니다.

8. 정기적으로 검토 및 반복

문서는 정적인 아티팩트가 아닙니다. 설명하는 소프트웨어와 함께 발전해야 하는 살아있는 개체입니다. 지속적인 검토와 반복은 필수적입니다.

• 동료 검토: 문서 검토를 표준 코드 검토 프로세스(예: 풀 리퀘스트를 통해)에 통합하십시오. 다른 팀원(개발자, 작성자, QA)이 명확성, 정확성, 완전성 및 스타일 가이드 준수 여부를 검토하도록 하십시오.
• 사용자 피드백 요청: 문서 사용자(내부 및 외부 모두)에게 피드백을 제공하도록 권장하십시오. 오류 보고, 개선 제안 또는 설명 요청을 쉽게 할 수 있도록 하십시오.
• 정기 검토 일정: 핵심 구성 요소 또는 기본 문서의 경우, 코드가 크게 변경되지 않았더라도 정확하고 관련성이 있으며 최신 상태인지 확인하기 위해 정기 검토(예: 분기별, 반기별) 일정을 잡으십시오.
• 코드 변경 시 업데이트: 이것은 근본적인 원칙입니다. 코드를 수정하면 동일한 변경 세트 또는 작업의 일부로 해당 문서를 업데이트하십시오. 이것이 Docs as Code 접근 방식의 핵심 이점입니다.

9. 가능한 경우 자동화

Docs as Code 철학에서 강조하는 것처럼 문서 품질을 향상시키고 일관성을 적용하며 수동 작업을 줄이기 위해 자동화를 활용하십시오.

• API 문서 생성: 소스 코드 주석에서 API 참조 문서를 자동으로 생성하는 도구(예: Java용 Javadoc, C++용 Doxygen, Python용 Sphinx autodoc, REST API용 OpenAPI Generator)를 사용하십시오.
• 린터 및 스타일 검사기: CI 파이프라인에 자동화된 도구를 통합하여 스타일 일관성, 문법, 철자 및 형식 규칙 준수 여부를 확인하십시오.
• 링크 검사기: 자동화된 도구를 사용하여 문서의 깨진 내부 또는 외부 링크를 정기적으로 스캔하십시오.
• 자동 빌드 및 배포: 변경 사항이 병합될 때마다 소스에서 문서를 자동으로 빌드하고 배포하는 CI/CD 파이프라인을 설정하여 항상 최신 버전이 게시되도록 하십시오.

10. 설계 결정 및 근거 문서화

코드가 무엇을 하고 어떻게 사용하는지를 문서화하는 것 외에도, 특히 중요한 아키텍처 선택에 대해 특정 설계 결정이 왜 이루어졌는지를 문서화하는 것은 종종 엄청나게 가치 있습니다.

• 아키텍처 결정 기록 (ADR): 중요한 아키텍처 결정, 결정이 이루어진 컨텍스트, 고려된 대안 및 선택된 접근 방식의 결과를 캡처하는 간결한 문서입니다. ADR은 미래 개발 및 유지보수를 위한 귀중한 역사적 컨텍스트를 제공합니다.
• 절충안 설명: 특정 기술 접근 방식 또는 설계 패턴이 다른 것보다 선택된 경우, 그 이유와 관련된 절충안(예: 성능 대 유지보수성, 보안 대 유용성)을 간략하게 설명하십시오.

11. DRY 원칙 준수 (반복하지 마십시오)

소프트웨어 개발에서 잘 알려진 "반복하지 마십시오(Don't Repeat Yourself)" 원칙은 문서에도 동일하게 적용됩니다. 중복된 정보는 유지보수하기 어렵고 불일치로 이어질 수 있습니다.

• 단일 정보 출처 추구: 정보 조각(예: 구성 설정, 아키텍처 개념)을 하나의 정식 위치에 정의하십시오.
• 링크 또는 트랜스클루전 사용: 다른 관련 문서 페이지에서 이 단일 정보 출처로 링크하십시오. 일부 고급 문서 도구는 한 파일의 콘텐츠를 다른 파일에 직접 포함할 수 있는 "트랜스클루전"도 지원하여 소스 업데이트가 모든 곳에 반영되도록 합니다.

12. 전 세계 독자를 위해 작성 (해당하는 경우)

소프트웨어 또는 라이브러리가 전 세계 독자를 대상으로 하거나 개발팀이 국제적으로 분산되어 있는 경우 다음 사항을 고려하십시오.

• 명확하고 간단한 영어 사용: 비원어민 영어 사용자가 이해하기 어려울 수 있는 문화적으로 특정한 관용구, 속어 또는 지나치게 복잡한 문장 구조를 피하십시오.
• 번역 및 현지화 고려: 다른 언어로의 번역이 계획되어 있다면, 원본 문서를 명확하고 직접적이며 문화적으로 중립적인 방식으로 작성하면 번역 프로세스를 크게 단순화할 수 있습니다. 일부 Docs as Code 설정은 문서의 번역된 버전을 관리하고 빌드하는 데도 도움이 될 수 있습니다.

button

결론: 문서의 미래를 받아들이기

"Docs as Code"는 단순한 도구 모음이나 새로운 워크플로우 그 이상입니다. 소프트웨어 개발 라이프사이클 내에서 문서를 일등 시민으로 격상시키는 근본적인 문화적 변화를 나타냅니다. 문서를 소프트웨어 코드와 동일한 주의, 엄격함, 협업 정신 및 반복 프로세스로 취급함으로써 팀은 일관되게 정확하고 쉽게 유지보수 가능하며 사용자에게 진정으로 가치 있는 동적이고 살아있는 정보 리소스를 만들 수 있습니다.

이 강력한 관리 프레임워크가 독자에 대한 깊은 집중, 흔들리지 않는 명확성, 실용적인 예제 및 지속적인 개선 약속과 같은 작성 모범 사례와 결합될 때, 그 결과는 새로운 팀원의 온보딩을 훨씬 빠르게 지원하고, 기술 토론의 모호성을 줄이며, 분야 간 더 나은 협업을 촉진하고, 궁극적으로 더 높은 품질의 소프트웨어 생성에 기여하는 문서입니다.

소프트웨어 시스템이 계속 복잡해지고 개발팀이 국제적으로 분산됨에 따라 Docs as Code를 수용하고 건전한 문서 작성 원칙을 준수하는 것은 더 이상 단순한 모범 사례가 아니라 지속 가능한 성공을 위한 절대적인 필수가 될 것입니다. 우수한 문서를 생산하고 유지보수하는 데 투자하는 것은 전체 소프트웨어 라이프사이클에 걸쳐 상당한 이익을 가져다주므로 모든 미래 지향적인 기술팀에게 필수적이고 전략적인 분야가 됩니다.