• 일전의 공부한 내용을 실제로 구현해보면서 공부해보고자 시작한 프로젝트다.
  • 이전 글
  • 아직 공부 중인 개념입니다. 조금 틀려도 너른 이해 부탁드립니다!
  • 이 글은 개인적인 의견을 다룹니다.

다루는 내용

문서 작성에 대한 고민 내용

문서 작성에 대해서

1.문서의 목표

  1. 시간에 구애 받지 않는 정보의 명확한 전달
  2. 의사 결정까지 도달하는 과정에 대한 문맥 제공
  3. 기반 지식에 대한 축적
  4. 문서를 기반으로 한 상호 이해도 증가와 협업에 대한 효율 증대
  5. 품질, 일관성 유지

1. 정보의 전달

  • 주변에 프로젝트를 진행하면서 히스토리를 아는 사람을 찾아다니고 물어보는 경우를 꽤 많이 봤다.
    • 물론 이는 나쁜 상황이 아니다.
    • 히스토리를 아는 사람이 있기 때문이다.
  • 만약 히스토리를 아는 사람이 없다면 어떻게 될까?
  • 실제로 프로젝트 내 두더지 굴을 깊이 파고 들어가는 경우를 봤다.
    • 이는 시간의 낭비로 이어진다.
    • 이는 효율성의 저하로 이어진다.
    • 이는 지금은 해결할 수 있지만 다음에는 장담하지 못하는 상황을 초래할지도 모른다.
  • 문서는 나를 위해 쓴다기 보다는 미래의 나 혹은 미래의 누군가를 위해서 작성한다.

2. 문맥 제공

  • 어떤 이유로 이러한 결과로 수렴되었는가?
    • 과거에는 맞고 현재는 틀리다.
    • 이를 증명하기 위해서는 당시 결정된 문맥이 필요하다.
  • 문제 해결에 대한 문맥의 제공은 문제 자체의 이해도를 높혀준다.
  • 미래에 현재 산출물에 대한 정당한 근거가 된다.
  • 또한 좋은 문서는 시간을 단축하고 판단 시간을 늘리는 도구가 되기도 한다.

3. 기반 지식의 축적

  • 문서화는 누적된다.
    • 그러나 많은 문서가 무조건 좋은 것은 아니다.
    • 올바른, 핵심적인 내용을 담는 것이 가치가 있다.
  • 쌓인 지식은 재산이 되고 이 지식은 프로젝트의 일부가 된다.

4. 협업 효율 증대

  • 프로덕트를 만들 때 유비쿼터스 언어로 소통하는 과정이 있다.
    • 문서화는 자연스럽게 이 과정을 돕는다.
    • 또한 구성원이 잊어버린 것에 대한 보충 역할을 한다.
  • 같은 문맥, 같은 이해도를 바탕으로 업무를 진행할 수 있어 효율성이 증가한다.

5. 품질

  • 문서는 프로덕트의 일부다.
  • 새로온 사람에게는 프로젝트를 이해하고 빠르게 적을할 수 있는 도구로
  • 오랫동안 프로덕트를 맡은 사람에게는 지식을 부담 없이 전수할 수 있는 매개가 된다.
  • 이는 양극단의 차이를 줄이고 결과적으로 프로덕트 자체의 품질을 올릴 수 있는 기반이 된다.

2. 문서의 종류

  1. README: 프로젝트의 목적 실행 방법 등 소스로써 프로젝트에 대한 간단한 설명을 제시한다.
  2. API-Spec:
    • Swagger, RestDocs 등을 사용해서 작성한다.
    • 외/내부 연동을 위한 계약 문서로써 효력을 갖는다.
    • 입력, 출력, 예외 등에 대한 것을 명확히 기술한다.
  3. ERD/ DomainModel
    • 데이터베이스 구조나 aggregate 구성 이해에 필수적이다.
  4. ADR(Architecture Decision Record)
    • 핵심 기술/ 설계 선택의 이유와 배경을 문서화 한다.
    • 미래의 회고나 팀 간 맥락 공유를 위해서 필요하다.
  5. 테스트 전략 문서
    • 어떤 단위 테스트에 어떤 테스트가 있는지
    • 어떤 시나리오를 상정하고 테스트를 작성했는지
    • 어떤 케이스를 커버하는지 정리
  6. 예외처리 및 에러 코드 정의서
    • 공통 예외, 도메인별 예외 설명
  7. 기능 설계서/ 흐름도/ 시퀀스 다이어그램/ 클래스 다이어그램
    • 복잡한 기능에 대한 개발 흐름을 공유
  8. 마이그레이션 및 버전 관리 문서
    • DB 변경, 구조 리팩토링 등의 히스토리
  9. 운영 및 장애 대응 메뉴얼
    • 모니터링 기준, 알림 조건, 대응 메뉴얼

3. 좋은 문서

  1. 명확하고 불필요한 중복이 없음
  2. 구조화되어 있어 빠르게 스캔이 가능
  3. 변경 사항을 쉽게 반영할 수 있다.
  4. 항상 최신의 상태를 유지
  5. “읽는 이의 입장에서 작성한 문서”

4. 원칙

1. 단일 소스 원칙(Single Source of Truth)

정보의 유일한 출처는 단 하나여야 한다.

  • 문서에 대한 내용이 특정 형식으로 관리된다면 다른 곳에서 반복하지 않아야 한다.
  • ex) API-Spec이 Swagger로 관리된다면, 그 외 문서에서는 다루지 않고 Swagger를 참조하게 해야 한다.
  • 장점
    • 유지 보수 비용 감소
    • 중복된 문서 간 불일치 방지
    • 명확한 정보의 책임 위치 생김

      2. DRY(Don’t Repeat Yourself)

  • 문서도 코드처럼 중복 장비

    3. Documentation as code

  • 문서도 코드처럼 버전 관리
  • 코드 변경과 함께 문서도 PR 단위로 관리

    4. Just Enough Documentation

  • 너무 자세하거나, 너무 적은 문서 모두 문제
  • 목적과 독자에 따라 필요한 만큼 장성

    5. Up-to-Date Principle

  • 최신이 아니면 없느니만 못 함

    6. Who-is-this-for Principle

  • 독자를 특정하고 작성하는 문서

그래서?

  • “개발자가 문서 작성을? “ 이라는 안일한 생각에 대해서 반성하게 됐다.
  • PR도 문서지만 일전에 고민하던대로 문서 작성도 프로젝트의 일부다! “어떤 문서가 더 의미가 있을까?”를 고민하고 작성하자