Chapter 10 - 문서자료

문서자료는 코드와 같다.

• 따라야 하는 내부 정책과 규칙이 있어야 한다.
• 버전 관리 시스템에 등록해 관리해야 한다.
• 관리 책임자를 명시해야 한다.
• 주기적으로 평가(혹은 테스트)를 받아야 한다.

구글 위키 사례

• 오래된 정보를 그대로 담고 있었습니다. 중복된 페이지들이 나타났습니다. 몇 개만이 제대로 유지보수되고 있었고, 대부분은 특정 권한이 있고 몇가지 가정을 충족하는 팀만을 위한 안내였습니다.

구글도 쉽지 않았다는 것에 위안도 된다.

독자를 알자

• 완벽할 필요는 없습니다. 테스트와 같이 엔지니어들이 지켜야 할 프로세스를 설명하는 글을 쓴다고 생각해보세요.
• 독자 유형
  • 경험 수준: 전문 프로그래머, 초보 엔지니어
  • 도메인 지식: 팀원, 혹은 최종 API 정도에만 친숙한 사내 다른 엔지니어
  • 목적: 급히 정보를 수행해야하거나 정보를 얻어야 하는 최종 사용자, 혹은 꼬여있는 특정 구현마저 기꺼이 책임지려 하는 소프트웨어 전문가
• 대부분의 경우 가능한 한 모든 독자에게 적합한 방식으로 쓰는 것이 하나의 요령입니다.
• 핵심은 균형을 잘 잡는 것입니다. 치트키는 없습니다.
• 하지만 '짧게' 쓰는 게 유리하다는 사실을 알아냈습니다.

독자의 유형을 구분해서 생각한다면 도움이 될 것 같다.

짧게는 문서에서도 유리하다.

• 독자 구분
  • 탐색자: 원하는 것을 정확히 알고, 정보를 찾는 엔지니어. 이런 독자에게는 일관성이 핵심
  • 배회자: 무엇을 원하는지를 정확하게 알지 못하는 사람, 맡겨진 기능을 어떻게 구현해야 할지에 대해 어슴푸레한 아이디어만 가지고 있을 것. 이런 독자에게는 명료한 글이 효과적

설계 문서

• 소프트웨어 엔지니어들은 일반적으로 팀에서 승인한 특정 템플릿을 이용해서 설계 문서 초안을 작성합니다.

기술자문 이후 Vue3, React와 같은 기술 스택이 정해졌다면, 구체적으로 어떤 라이브러리, 디렉토리 구조, 컴포넌트, 컴포넌트간 데이터 흐름등 조금 더 깊은 설계를 해보는 것도 좋을 것 같다.

문서자료 리뷰

• 문서자료 역시 리뷰를 거쳐야 합니다. 크게 세 가지입니다. 각각은 서로 다른 측면을 중점적으로 살핍니다.
  • 정확성
  • 명확성
  • 일관성

주석에도 위와같은 면을 살핀다면 더 좋은 주석을 작성할 수 있을까?

문서화 철학

• 어떻게에만 매몰되지 말고, '누가' '무엇을' '언제' '어디서' '왜'도 고려하자
• 시작, 중간, 끝처럼 문서에 절을 추가하는 것을 두려워하지 말자

핵심 정리

• 문서자료는 시간이 흐르고 조직 규모가 커질수록 더 중요해집니다.
• 문서자료 변경도 기존 개발자 워크플로에 통합되어야 합니다.
• 하나의 문서는 하나의 목적에 집중해야 합니다.
• 문서자료는 자신이 아니라 독자를 위해 써야 합니다.

느낀 점

• 코드 주석 외에 작성해야할 어떤 문서가 있을지 구체적인 상상이 안간다. Next.js나 CloudFlare, Claude의 문서를 떠올리면 될까? 아니면 기타 NPM 패키지들? 그런 문서를 우리 회사에서 작성해야하나? 최근에는 기술자문이 생겼다.