대부분의 엔지니어의 대표적인 불만이 양질의 문서자료가 부족하다는 것이다. 현실적으로 대부분의 문서자료는 소프트웨어 엔지니어 스스로가 작성해야 한다. 따라서 엔지니어가 문서화를 효과적으로 할 수 있도록 도와주는 적절한 도구와 보상이 필요하다.
구글에서 문서자료를 개선하고자 해본 시도 중 가장 성공적이었던 방법은 문서자료를 코드처럼 취급하여 엔지니어링 워크플로에 통합하는 것이다. 그 결과 엔지니어들이 간단한 문서자료를 작성하고 유지보수하는 일이 한결 수월해졌다.
10.1 문서자료란?
문서자료란 엔지니어가 작업을 끝마치기 위해 작성해야 하는 모든 부수적인 텍스트를 의미한다.(코드 주석까지 포함됨)
10.2 문서자료가 필요한 이유
양질의 문서자료는 엔지니어링 조직에서 커다란 축복이다. 코드와 API가 이해하기 다 쉬워지고, 실수가 줄어든다. 하지만 문서자료가 주는 혜택은 주로 후임자들에게 돌아가므로 작성자에게는 즉각적인 이득이 없는 경우가 많다.
문서자료는 단 한 번만 작성하면 되지만 결국 수백 번, 수천 번 읽히게 된다. 초기 비용은 미래의 모든 독자에게 혜택으로 돌아간다.
문서작료는 작성자에게 다음과 같은 혜택을 준다.
- API를 가다듬는데 도움을 준다. 문서화를 하다보면 자연스럽게 자신의 설계를 되돌아보게 된다.
- 유지보수를 위한 로드맵과 과거 이력을 제공한다.
- 코드를 더 전문적이고 매력있어 보이게 한다.
- 이용자들의 질문이 줄어든다. 만약 다른이에게 두 번 이상 똑같은 설명을 하고 있는 자신을 발견한다면 그 내용을 문서화하는 것이 좋다.
10.3 문서자료는 코드와 같다
문서 쓰기는 코드 작성과 크게 다르지 않다. 프로그래밍 언어처럼 규칙이 있고, 구문 규정이 있고, 스타일도 있다. 코드와 마찬가지로 일관되어야 하고, 명확해야 하고, 이해를 방해하는 오류를 피해야 한다. 기술문서를 작성할 때는 문법도 중요하기 때문에 구글에서는 코드 주석도 프로그래밍 언어별로 표준 스타일을 정해놨다.
문서자료를 다음과 같이 취급해야 한다.
- 꼭 따라야하는 내부 정책과 규칙이 있어야 한다.
- 버전 관리 시스템에 등록해 관리해야 한다.
- 관리 책임자를 명시해야 한다.
- 변경시 리뷰를 거쳐야 한다.
- 코드상의 버그를 추적하듯 문제를 추적해야 한다.
- 주기적으로 평가를 받아야 한다.
- 가능하다면 정확성이나 최신 정보 반영 여부등을 측정해야 한다.
사례연구) 260p
10.4 독자를 알자
엔지니어들이 문서자료를 작성하며 범하는 가장 큰 실수는 자신만을 위해 쓴다는 것이다. 하지만 실제로는 그 문서자료의 독자는 사내의 모든 엔지니어와 외부 개발자까지 상당히 다양할 수 있다. 그래서 문서자료를 작성하기 전에 만족시켜야 할 독자가 누구인지 공식적으로든 비공식적으로든 알아내야 한다.
10.4.1 독자 유형
도메인 지식을 독자의 눈높이에 맞는 기술 수준으로 써야 한다
- 경험수준 : 전문 프로그래머 또는 초보 엔지니어
- 도메인 지식 : 팀원, API 정도만 친숙한 사내의 다른 엔지니어
- 목적 : API를 사용하는 최종 사용자 또는 책임감 있는 소프트웨어 전문
대부분의 경우에는 가능한 한 모든 독자에게 적합한 방식으로 쓰는 것이 하나의 요령이다. 문서 작성의 핵심은 균형을 잘 잡는 것으로 문서를 짧게 쓰는게 유리하다.
사용자가 문서자료를 접하게 되는 방식에 따라서 독자를 구분해볼 수 있다.
- 탐색자 : 자신이 원하는 것을 정확히 알고, 읽고 있는 문서자료가 원하는 정보를 담고 있는지를 알고 싶어 하는 엔지니어이다. 이런 독자에게는 일관성 이 핵심이다.
- 배회자 : 무엇을 원하는지 정확하게 알지 못하는 사람이다. 이런 독자에게는 명료한 글이 효과적이다.
또 고객(API 사용자)냐 제공자(프로젝트 팀원)이냐도 중요한 독자 구분 기준이다. 가능하다면 각각의 독자를 위한 문서를 구분해주는 것이 좋다.
10.5 문서자료 유형
엔지니어는 개발 과정에서 설계 문서, 코드 주석, How-to 문서, 프로젝트 페이지 등 다양한 문서자료를 작성한다. 중요한 것은 종류가 다름을 알고 서로 섞이지 않게 하는 것이다. 하나의 문서는 일반적으로 하나의 목적에 집중해야 한다.
10.5.1 참조용 문서자료
참조용 문서자료는 엔지니어가 작성해야 할 문서자료 중 가장 흔한 형태이다. 실제로 거의 매일 작성해야 한다. 대표적인 예로 코드 주석이 있다. 이는 엔지니어들이 반드시 유지보수해줘야 한다.
- API 주석 - 구체적인 구현 방법이나 설계 결정 사항은 언급할 필요 없다. 사용자가 작성자만큼 API에 대해 잘 안다고 가정해서는 안 된다.
- 구현 주석 - 읽는 이가 도메인 지식을 상당히 갖추고 있다고 가정해도 된다.
파일 주석
구글에서는 거의 모든 파일에 파일 주석이 적혀있어야 한다. 일반적으로 파일 주석에는 파일에 담겨있는 내용을 요약해줘야 한다. (해당 코드의 주요 쓰임새와 어떤 독자를 의도하고 만든 코드인지 명시)
클래스 주석
클래스 주석은 코드베이스에서 사용되는 API 객체들을 정의하는 중요한 주석이다. 구글에서 모든 공개 클래스는 클래스 주석을 담고 있어야 한다.(해당 클래스의 목적과 주요 메서드들을 설명)
함수 주석
구글에서는 자유 함수나 클래스의 공개 메서드에는 무조건 함수가 무슨 일을 하는지 설명하는 함수 주석이 있어야 한다. 함수주석은 함수가 무슨 동작을 하고 무엇을 반환하는지를 설명하고 능동성을 부각하기 위해 동사로 시작해야 한다.
10.5.2 설계 문서
구글의 팀 대부분은 중요한 프로젝트에 착수하기 전에 설계 문서부터 승인받아야 한다. 엔지니어들은 일반적으로 팀에서 승인한 특정 템플릿을 이용해서 설계 문서 초안을 작성한다.
좋은 설계 문서라면 설계의 목표와 구현 전략을 설명하고 설계상의 핵심 선택들과 관련한 트레이드오프를 명시해야 한다. 즉 설계 목표를 제시하고 대안이 될 수 있는 설계들의 장점과 단점까지 함께 기술해줘야 한다. 그리고 설계된 문서는 프로젝트가 목표를 성공적으로 완수했는지를 평가하는 기초 자료로 활용해야 한다.
10.5.3 튜토리얼
새로 팀에 합류한 엔지니어들을 위해 프로젝트 환경을 새로 구축하는 과정을 담은 튜토리얼이 아주 중요하다. 튜토리얼은 모든 팀원이 올바른 첫 발을 내딛는데 가장 좋은 방법 중 하나다.
튜토리얼을 작성은 수행해야 했던 모든 일을 적는 것이다. 어떠한 사전 설정, 권한, 도메인 지식도 가정하지 말라 무언가 먼저 설정되어 있다고 가정했다면 튜토리얼 앞부분의 사전 요구사항 절에 명시하라 대부분의 튜토리얼은 전체 과정을 여러 단계로 나눠 독자가 순서대로 수행하도록 안내한다. 이런 경우 각 단계에 명확한 번호를 붙여야 한다.
10.5.4 개념 설명 문서
어떤 코드는 코드 주석 같은 참조용 문서자료만으로는 부족하여 깊이 있는 설명을 곁들여야 한다. 이럴때 시스템의 개요를 알려주는 개념 문서를 첨부한다. 개념 문서는 벌어질 수 있는 모든 상황을 다 설명하지 않아도 된다. 개념을 더 명확하게 전달하는 게 목적이라서 정확성을 다소 희생할 수 있다.
개념 문서는 전문가에서 초보자까지 많은 독자에게 유익해야 한다. 그리고 명확성이 중요하므로 다소 완전하지 않거나 때로는 정확성을 희생하곤 한다.
10.5.5 랜딩 페이지
팀 페이지들은 대부분 어수선하다 랜딩 페이지에는 흥미를 끄는 링크들이 보일 것이고, 팀원용 정보와 고객용 정보가 섞여 있기도 할 것이다. 이런 문서들을 수정하기 위해서 랜딩 페이지의 목적을 명확히 인식하고 자세한 정보는 모두 다른 페이지를 가리키는 링크로 대체하면 된다. 랜딩 페이지에 링크가 많다면 절을 구분해서 페이지를 분류별로 분할하는 게 좋다.
10.6 문서자료 리뷰
구글은 코드 리뷰 외에 일반적으로 문서자료 역시 리뷰를 거쳐야 한다. 기술 문서 리뷰에 효과적인 방식은 크게 세 가지이다.
- 정확성 확인용 기술 리뷰 : 주로 해당 주제의 전문가가 수행하며 코드 리뷰 과정에서 함께 다루곤 한다.
- 명확성 확인용 독자 리뷰 : 주로 도메인을 잘 모르는 사람이 수행한다.
- 일관성 확인용 작문 리뷰 : 주로 테크니컬 라이터나 자원자가 수행한다.
사례연구) 개발자 가이드 273p
10.7 문서화 철학
10.7.1 누가, 무엇을, 언제, 어디서, 왜
대부분의 기술 문서자료는 어떻게에 대한 답을 제시한다. 그래서 엔지니어들은 다른 질문들은 잊은채 어떻게만 생각하는 경향이 생겼다.
- 누가 : 대상 독자가 누구인지
- 무엇 : 문서의 목적
- 언제 : 문서가 생성되고, 리뷰되고, 갱신된 날짜
- 어디에 : 문서가 존재해야 할 장소
- 왜 : 문서의 목적, 문서를 읽은 독자가 무엇을 얻어가기를 바라는지를 요약한다.
10.7.2 시작, 중간, 끝
대부분의 엔지니어는 중복을 꺼린다. 하지만 문서자료에서는 중복이 때론 유용하다. 각 절의 도입 단락에서 핵심을 요약해 알려준 후 해당 절의 나머지에서 구체적으로 사례를 설명하는 방법이 독자가 중요 내용을 이해하는 데 중복이 도움이 된다.
10.7.3 좋은 문서자료의 특징
일반적으로 좋은 문서자료들은 세 가지 특징을 보인다. (완전성, 정확성, 명확성) 하지만 하나의 문서에 세 특징을 모두 담기는 어렵다. 예) 문서를 더 완벽하게 만들려다 보면 명확성이 떨어지기 쉽다. 결국 좋은 문서란 의도한 역할을 잘 수행하는 문서라고 할 수 있다. 따라서 하나의 문서에 둘 이상의 역할을 맡기는 일은 거의 없다. 각각의 문서는 무엇에 집중할지를 정하고 그에 맞게 작성되야 한다.
10.7.4 문서 폐기하기
오래된 코드와 마찬가지로 오래된 문서도 문제를 일으키곤 한다. 그래도 문서를 버리는 일은 되도록 생기지 않도록 노력해야 한다. 문서가 본래의 목적을 더 이상 수행할 수 없다면 폐기하거나 폐기 대상으로 표시해줘야 한다.
구글에서는 문서자료에 신선도 보증 기간을 붙여두곤 한다. 마지막에 리뷰한 날짜를 기록해두면 이 데이터를 활용하여 3개월동안 갱신되지 않을 시 알림 메일을 보내는 식이다.
10.8 테크니컬 라이터가 필요한 순간
구글의 엔지니어링 팀 대다수가 팀에 필요한 문서자료를 스스로 완벽하게 작성할 수 있음을 깨달았다. 다른 이의 도움이 필요한 경우는 오직 팀원 외 독자를 위한 문서를 작성할 때뿐이었다.
테크니컬 라이터는 도메인에 익숙하지 않은 사람을 더 잘 대변할 수 있다. 그래서 테크니컬 라이터의 핵심 역할 하나가 프로젝트가 어디에 유용한가에 관한 팀 내 가정에 의문을 품어보는 것이다.
10.9 마치며
10.10 핵심 정리
- 문서자료는 시간이 흐르고 조직 규모가 커질수록 더 중요해진다.
- 문서자료 변경도 기존 개발자 워크플로에 통합되어야 한다.
- 하나의 문서는 하나의 목적에 집중해야 한다.
- 문서자료는 자신이 아니라 독자를 위해 써야 한다.