구글 엔지니어는 이렇게 일한다

10. 문서자료

주요 내용

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

엔지니어들이 양질의 문서자료를 더 쉽게 작성하도록 하는 비결이 무엇일까요? 바로 현재 개발 워크플로에 긴밀하게 통합되고 조직의 성장에 발맞춰 확장되는 프로세스와 도구입니다. 문서자료를 코드처럼 취급하여 엔지니어링 워크플로에 통합해야 합니다.

1. 문서자료의 필요성

이번 장에서 말하는 문서자료(documentation)란 엔지니어가 작업을 끝마치기 위해 작성해야하는 모든 부수적인 텍스트를 의미합니다. 그러므로 별도로 작성한 문서뿐 아니라 코드 주석까지 포함합니다.
문서자료는 이렇게 설계한 이유, 이렇게 코드를 구성한 이유 등을 설명해주는 중요한 역할을 하지만 엔지니어들이 '덜 중요하게' 생각하는 이유가 무엇일까요?

• 혜택이 (특히 작성자에게) 즉각적으로 돌아오지 않는다.
• 많은 엔지니어가 글쓰기를 프로그래밍과는 별개의 기술로 본다. (이 시각은 잘못되었다. 글쓰기는 SW 엔지니어링에 꼭 필요한 기술이다.)
• 글쓰기에 자신없어 하는 엔지니어도 있다. (영어에 꼭 유창해야만 양질의 문서자료를 작성할 수 있는 것은 아니다.)
• 문서자료는 도구 지원이나 개발 워크플로 통합 측면에서 아직 만이 부족하기 때문에 작성하기가 상대적으로 더 어렵다.
• 문서자료를 유지보수할 대상이 하나 더 늘어난 짐으로 생각한다.

하지만 문서자료는 다음과 같은 혜택을 줍니다.

• API를 가다듬는데 도움이 된다.
• 유지보수를 위한 로드맵과 과거 이력을 제공한다. (코딩에서 꼼수는 무조건 피해야 하지만, 어쩔 수 없다면 주석이라도 잘 달아둬야 한다.)
• 코드를 더 전문적이고 매력 있어 보이게 한다. (실제로 문서화가 잘되어 있는 제품은 유지관리가 잘되고 있는 제품일 확률이 높다.)
• 이용자들의 질문이 줄어든다.

문서자료는 세월이 흐를수록 더 중요해지며, 특히 핵심 코드를 잘 문서화해두면 조직이 커질수록 지대한 기여를 합니다.

2. 문서자료는 코드와 같다

문서자료에도 프로그래밍 언어처럼 규칙이 있고, 구문 규정이 있고, 스타일도 있습니다. 코드와 마찬가지로 일관되어야 하고, 명확해야 하고, 이해를 방해하는 오류를 피해야 합니다. 이는 설명하는 문체를 표준화하고 혼동 요소를 없애 독자가 헷갈리지 않게 하기 위함입니다.
따라서 문서자료는 다음과 같이 취급해야합니다.

• 꼭 따라야 하는 내부 정책과 규칙이 있어야 한다.
• 버전 관리 시스템에 등록해 관리해야 한다.
• 관리 책임자를 명시해야 한다.
• 변경 시 (문서자료가 설명하는 코드와 함께) 리뷰를 거쳐야 한다.
• 코드상의 버그를 추적하듯 문제를 추적해야 한다.
• 주기적으로 평가(혹은 테스트)를 받아야 한다.
• 가능하다면 정확성이나 최신 정보 반영 여부 등을 측정해야 한다.

3. 문서자료는 독자에 맞게 쓰자

엔지니어들이 문서자료를 작성하며 범하는 가장 중요한 실수는 자신만을 위해 쓴다는 것입니다. 좋은 문서자료라 해서 완벽할 필요는 없습니다. 하지만 독자가 누구인지는 꼭 파악한 후에 작성해야 합니다. 그리고 문서를 짧게 쓰는 것이 유리합니다. 독자 유형은 다음과 같이 나눌 수 있습니다.

• 경험 수준: 전문 프로그래머, 혹은 프로그래밍 언어조차 낯선 초보 엔지니어
• 도메인 지식: 팀원, 혹은 최종 API 정도에만 친숙한 사내 다른 엔지니어
• 목적: 제공하는 API를 사용해 특정 작업을 수행하거나 급히 정보를 얻어내야 하는 최종 사용자 등

사용자가 문서 자료를 접하게 되는 방식에 따라서 독자를 구분할 수 있습니다.

• 탐색자(seeker)
  자신이 원하는 것을 정확히 알고, 읽고 있는 문서자료가 원하는 정보를 담고 있는지를 알고 싶어 하는 엔지니어 입니다. 이럴 때는 일관성이 핵심입니다. 비슷한 포맷을 일관되게 적용하는 것이 좋습니다.
• 배회자(stumbler)
  무엇을 원하는지를 정확하게 알지 못하는 사람입니다. 이럴 때는 명료한 글이 효과적 입니다. 예를 들어 파일의 맨 위에 개요나 소개 절을 두어 파일에 담겨 있는 코드의 목적을 설명할 수 있습니다.

[TL;DR문]
구글에서는 어떤 독자에게 적합하지 않은 문서인지도 알려줍니다.
예를들어 다음과 같이 TL;DR문을 사용해 표시합니다.
- TL;DR: 구글의 C++컴파일러가 궁금한 것이 아니라면 더 읽을 필요 없습니다. 

마지막으로 고객(ex. API 사용자)이냐 제공자(ex. 프로젝트 팀원)이냐도 중요한 독자 구분 기준입니다. 가능하다면 각각의 독자를 위한 문서를 구분해주는 것이 좋습니다. 각자에게 필요한 정보가 다르기 때문입니다.

4. 문서자료의 유형

다양한 문서자료의 종류가 다름을 알고 서로 섞이지 않게 하는 것도 중요합니다. 하나의 문서는 일반적으로 하나의 목적에 집중해야 합니다.

1. 참조용 문서자료
   코드베이스에 속한 코드의 사용법을 설명하는 문서 모두를 일컫습니다. 가장 대표적인 예는 코드 주석입니다.

[코드 주석의 분류]
API 주석
- 구체적인 구현 방법이나 설계 결정 사항을 언급할 필요는 없음
- 사용자가 작성자만큼이나 API에 대해 잘 안다고 가정해서는 안됨
구현 주석
- 읽는 이가 도메인 지식을 상당히 갖추고 있다고 가정해도 됨

• 파일 주석
  파일에 담겨 있는 내용을 요약해야 한다. 간결하게 설명할 수 없는 API라면 API의 설계가 잘못된 것일 수 있다.
• 클래스 주석
  구글에서는 모든 공개 클래스(+구조체)는 클래스 주석을 담고 있어야 한다. 목적과 주요 메서드를 설명한다.
• 함수 주석
  구글에서는 자유함수나 클래스의 공개 메서드에는 무조건 함수가 무슨 일을 하는지 설명하는 함수 주석이 있어야 한다. 능동성을 부각하기 위해 동사로 시작해야 한다. parameters, returns, throws 등의 섹션을 구분하지 않고 하나의 문장으로 표현하는 것이 더 명확하다.

2. 설계문서
   구글의 팀 대부분은 중요한 프로젝트에 착수하기 전에 설계 문서부터 승인받아야 한다.

3. 튜토리얼
   튜토리얼은 프로젝트 환경을 새로 구축하는 과정을 담은 것입니다. 튜토리얼이 아직 없다면 누군가가 팀에 새로 합류했을 때입니다. 튜토리얼에는 어떠한 사전 설정, 권한, 도메인 지식도 가정하면 안됩니다. 무언가 먼저 설정되어 있다고 가정했다면 튜토리얼 앞부분의 사전 요구사항 절에 명시하세요.

4. 개념 설명 문서
   어떤 코드는 코드 주석 같은 참조용 문서자료만으로는 부족하여 깊이 있는 설명을 곁들여야 합니다. 이 때 해당 API나 시스템의 개요를 알려주는 개념문서를 첨부합니다. 개념 문서는 참조 문서자료들을 대체하기보다는 보강하는 역할입니다. 개념문서는 명확성이 중요하므로 다소 완전하지 않거나 (완전한 문서 역할은 참조문서가 담당) 때로는 정확성을 희생하곤 합니다.

5. 랜딩 페이지
   랜딩 페이지는 홈페이지의 교통경찰 역할을 합니다. 랜딩페이지의 목적을 명확히 인식하고 자세한 정보는 모두 다른 페이지를 가리키는 링크로 대체합니다. 랜딩페이지의 두가지 역할은 1)해당 팀 제품의 고객이나 API 사용자를 위한 goto 페이지 역할이고, 2)다른 하나는 팀의 홈페이지 역할입니다. 절대 두 역할을 한 페이지에서 수행하면 안됩니다.

코드 주석이 문서자료계의 단위 테스트라면, 개념 문서는 통합 테스트이다.

5. 문서자료의 리뷰

문서자료 역시 리뷰를 거쳐야 합니다. 기술 문서 리뷰에 효과적인 방식은 크게 세가지 입니다.

• 정확성 확인용 기술 리뷰
  주로 해당 주제 전문가가 수행하며, 팀 동료인 경우가 많습니다. 코드 리뷰 과정에서 함께 다루곤 합니다.

• 명확성 확인용 독자 리뷰
  주로 도메인을 잘 모르는 사람이 수행합니다. 팀에 새로 합류한 동료나 해당 API의 고객일 것입니다.

• 일관성 확인용 작문 리뷰
  주로 테크니컬 라이터나 자원자가 수행합니다.

6. 문서화 철학

1. 누가 / 무엇을 / 언제 / 어디서 / 왜
   대부분의 기술 문서 자료는 HOW에 대한 답을 제시합니다. 하지만 다음 질문들에 답하는 것이 더 도움 될 것입니다.
   WHAT: 문서의 목적
   WHEN: 문서가 생성되고, 리뷰되고, 갱신된 날짜
   WHERE: 문서가 존재해야 할 장소
   WHY: 문서의 목적 (=요약, 문서의 소개 부분에 명시)

2. 시작 / 중간 / 끝
   문서에 절을 추가하면 내용 흐름을 논리적 조각으로 나눌 수 있습니다. 또한 독자에게 문서가 다루는 내용의 로드맵을 제시할 수 있습니다. 각 절의 도입 단락에서 핵심을 요약해 알려준 후, 해당 절의 나머지에 구체적으로 사례를 설명하는 방법이 좋습니다.

3. 좋은 문서자료의 특징
   완전성(Completeness), 정확성(Accuracy), 명확성(Clarity) 이 세가지가 좋은 문서의 특징이지만 하나의 문서에 세 특징을 다 담기는 어렵습니다. 결국 '좋은 문서'란 의도한 역할을 잘 수행하는 문서여야 합니다.
   

4. 문서 폐기하기
   본래의 목적을 더 이상 수행할 수 없다면 폐기하거나 '폐기 대상'으로 표시해야 합니다. 구글에서는 문서자료에 '신선도 보증 기간freshness date'을 붙여두곤 합니다.

7. 테크니컬 라이터가 필요한 순간은?

구글은 예전에 중요하다고 생각되는 프로젝트에는 팀에 정말 필요한지와 상관없이 테크니컬 라이터를 배정하는 경향이 있었습니다. 하지만 이는 잘못된 가정으로 판명됐습니다. 엔지니어들은 팀에 필요한 문서자료를 스스로 완벽하게 작성할 수 있습니다. 테크니컬 라이터가 필요한 경우는 오직 팀원 외 독자를 위한 문서를 작성할 때뿐입니다.