- 대부분의 엔지니어의 불만은 양질의 문서자료가 부족하다는 것이다.
- Side effect, 튜토리얼 중 에러, 약어 설명, 최신화 시점 등
- 테크니컬 라이터와 프로젝트 매니저가 도움을 줄 수는 있지만 현실적으로 대부분의 문서자료는 소프트웨어 엔지니어가 스스로 작성해야 한다.
- 엔지니어가 문서화를 효과적으로 할 수 있도록 도와주는 적절한 도구와 보상이 필요하다.
- 양질의 문서자료를 더 쉽게 작성하도록 하는 비결은 현재 개발 워크플로에 긴밀하게 통합되고 조직의 성장에 발맞춰 확장되는 프로세스와 도구이다.
- 2010년 후반 문서자료 실태는 상황은 1980년대 후반 소프트웨어 테스트의 상황과 유사하게 문서자료 개선에 힘써야 한다는 사실은 모두가 알지만 조직 차원에서는 문서자료가 주는 핵심 이점이 무엇인지 이해하지 못하고 있다.
- 구글은 문서자료를 코드처럼 취급하여 엔지니어링 워크플로에 통합하는 방법이 유효했다.
- 엔지이어가 작업을 끝마치기 위해 작성해야 하는 모든 부수적인 텍스트
- 별도로 작성한 문서뿐 아니라 코드 주석까지 포함된다.
- 양질의 문서자료가 있으면 코드와 API가 이해하기 더 쉬워지고 실수가 줄어든다.
- 프로젝트 팀들은 자신들의 설계 목표와 팀의 목표가 활자로 명확하게 적혀있을 때 역량을 더 집중하게 된다.
- 수동으로 해야 하는 일은 절차가 잘 기술되어 있어야 쉬워진다.
- 새로운 인력을 팀이나 코드베이스에 안착시키는 데 드는 노력이 줄어든다.
- 문서자료는 단 한 번만 작성하면 되지만 결국 수백 번, 수천 번 읽히게 된다. 초기 비용은 미래의 모든 독자에게 혜택으로 돌아간다.
- 이 설계를 택한 이유가 뭐지?
- 코드를 왜 이런 식으로 구현했을까?
- 내가 왜 이렇게 구현했지?
- 이런 혜택에도 불구하고 엔지니어들이 덜 중요하게 생각하는 이유
- 혜택이 (특히 작성자에게) 즉각적으로 돌아오지 않는다.
- 글쓰기를 프로그래밍과 별개의 기술로 본다. (다르다 해도 글쓰기는 소프트웨어 엔지니어링에 반드시 필요한 기술이다)
- 글쓰기에 자신 없어하는 엔지니어도 있다. (사용자 관점에서 작성하기가 중요하지 유창한 것은 상대적으로 덜 중요하다)
- 문서자료는 도구 지원이나 개발 워크플로 통합 측면에서 아직 많이 부족하기 때문에 작성하기가 상대적으로 더 어렵다.
- 문서자료가 기존 코드를 유지보수하기 더 쉽게 해준다고 생각하기보다는 유지보수할 대상이 하나 더 늘어난다고 생각한다.
- 조직은 어느 시점이 되면 문서화에 얼마나 많은 노력을 기울일지 결정해야 한다.
- 문서자료는 작성자에게도 다음과 같은 혜택을 준다.
- API를 가다듬는 데 도움을 준다. API 문서는 API가 가치가 있는지를 알아내는 가장 확실한 방법 중 하나이다. 문서화를 하다 보면 자연스럽게 자신의 설계를 되돌아보게 된다. API를 말끔히 설명하거나 정의할 수 없다면 설계가 미흡했을 가능성이 크다.
- 유지보수를 위한 로드맵과 과거 이력을 제공한다. 코딩에서 꼼수는 무조건 피해야 하지만, 어쩔 수 없다면 주석이라도 잘 달아둬야 한다. 잘만 작성해두면 2년 전 코드에서 문제점을 찾아야 하는 경우 큰 도움이 될 것이다.
- 코드를 더 전문적이고 매력 있어 보이게 한다. 개발자들은 무의식적으로 문서화가 잘 되어 있는 API를 더 잘 설계된 API라고 여긴다. 항상 그런 것은 아니지만 일반적으로 상관성이 높다. 문서화가 잘 되어 있는 제품은 유지관리가 잘 되고 있는 제품일 확률이 높기 때문이다.
- 이용자들의 질문이 줄어든다. 만약 다른 이에게 두 번 이상 똑같은 설명을 하고 있는 자신을 발견한다면 그 내용을 문서화하는 게 좋다.
- 읽는 이에게 최적화하라.
- 핵심 코드를 잘 문서화해두면 조직이 커질수록 지대한 기여를 한다.
문서자료를 코드와 동일하게 변경을 추적하게 만들자.
- 문서자료도 하나의 도구이자 특정 작업을 완수하기 위해 사용하는 또 하나의 언어다.
- 구글 문서자료용 스타일 가이드(https://developers.google.com/style)
- 코드처럼 문서에도 소유자가 있다. 소유자가 없는 문서는 점점 낡아져서 유지보수하기 어려워진다. 반대로 소유권이 명확하면 문서자료 업데이트를 버그 추적 시스템과 코드 리뷰 도구 같은 기존 개발 워크플로에 통합하기 수월하다.
- 소유자가 다른 문서끼리는 내용이 상충할 수 있다. 이런 경우 표준 문서를 하나 지정하는 게 좋다. 이후 다른 관련 문서들을 통합하거나 폐기 대상으로 지정한다.
- 문서자료 취급
- 꼭 따라야 하는 내부 정책과 규칙이 있어야 한다.
- 버전 관리 시스템에 등록해 관리해야 한다.
- 관리 책임자를 명시해야 한다.
- 변경 시 문서자료가 설명하는 코드와 함께 리뷰를 거쳐야 한다.
- 코드상의 버그를 추적하듯 문제를 추적해야 한다.
- 주기적으로 평가(혹은 테스트)를 받아야 한다.
- 가능하다면 정확성이나 최신 정보 반영 여부 등을 측정해야 한다.
- 문서자료를 작성하며 저지르는 가장 큰 실수는 자신만을 위해 쓴다는 것이다.
- 자신만을 위해 쓰면 특정한 가정들이 녹아들기 쉽다. 독자는 사내의 모든 엔지니어와 외부 개발자까지 다양하므로 이를 고려해야 한다.
- 문서자료를 작성하기 전에 만족시켜야 할 독자가 누구인지를 공식적으로든 비공식적으로든 알아내야 한다.
- 도메인 지식을 독자의 눈높이에 맞는 기술 수준으로 써야 한다고 했지만, 그 독자란 정확히 누구인가?
- 경험 수준: 전문 프로그래머, 혹은 프로그래밍 언어조차 낯선 초보 엔지니어
- 도메인 지식: 팀원, 혹은 최종 API 정도에만 친숙한 사내의 다른 엔지니어
- 목적: 여러분이 제공하는 API를 사용해 특정 작업을 수행하거나 급히 정보를 얻어내야 하는 최종 사용자, 혹은 아무에게도 유지보수를 맡기고 싶지 않을 만큼 꼬여 있는 특정 구현마저 기꺼이 책임지려 하는 소프트웨어 전문가
- 문서 작성의 핵심은 균형을 잘 잡는 것이다.
- 문서를 짧게 쓰는 것이 유리하다. 그러려면 때로는 모든 정보를 담아 길게 쓴 다음 간명하게 편집하고 중복된 정보를 삭제하는 과정을 거쳐야 한다.
- 문서자료를 접하게 되는 방식에 따른 독자 구분
- 탐색자(seeker): 자신이 원하는 것을 정확히 알고, 읽고 있는 문서자료가 원하는 정보를 담고 있는지를 알고 싶어하는 엔지니어. 이런 독자에게는 일관성이 핵심이다. 탐색자용 문서자료를 작성한다면 비슷한 포맷을 일관되게 적용하는 것이 좋다. 그러면 독자가 빠르게 훑으며 자신이 찾는 내용이 맞는지 판단하기 편할 것이다.
- 배회자(stumbler): 무엇을 원하는지를 정확하게 알지 못하는 사람. 아마도 맡겨진 기능을 어떻게 구현해야 할지에 대해 어슴푸레한 아이디어만 가지고 있을 것이다. 이런 독자에게는 명료한 글이 효과적이다. 가령 각 파일 맨 위에 개요나 소개 절을 두어 파일에 담겨 있는 코드의 목적을 설명한다. 어떤 독자에게 적합하지 않은 문서인지를 알려주는 것도 유용하다. 실제로 구글 문서 중 상당수는 가령 'TL;DR: 구글의 C++ 컴파일러가 궁금한 게 아니라면 더 읽을 필요 없습니다'와 같이 'TL;DR문'으로 시작한다.
- 고객(API 사용자)이냐 제공자(프로젝트 팀원)이냐도 중요한 독자 구분이다. 가능하다면 각각의 독자를 위한 문서를 구분한다. 구현과 관련한 자세한 내용은 코드를 유지보수해야 하는 팀원에게는 중요하지만 최종 사용자는 알 필요가 없는 정보다.
- 개발 과정에서 설계 문서, 코드 주석, How-to 문서, 프로젝트 페이지 등 다양한 문서자료를 작성하지만, 중요한 것은 종류가 다름을 알고 서로 섞이지 않게 하는 것이다.
- 하나의 API가 두 가지 일을 하면 안 되듯 하나의 문서에서 여러 가지 일을 하려 해서는 안 된다.
- 주요 문서 종류
- 참조용 문서자료(코드 주석 포함)
- 설계 문서
- 튜토리얼
- 개념 설명 문서자료
- 랜딩 페이지
- 해당 문서에 넣기에 적절치 않아 보이는 내용이 있다면 아마도 그 목적에 더 적합한 문서가 따로 있거나, 혹은 새로 만들어야 한다는 신호다.
- 참조용 문서자료는 코드베이스에 속한 코드의 사용법을 설명하는 문서 모두를 일컫는다.
- 코드 주석은 API 주석과 구현 주석으로 나뉜다. API 주석에는 구체적인 구현 방법이나 설계 결정사항은 언급할 필요 없다. 반면 구현 주석에서는 읽는 이가 도메인 지식을 상당히 갖추고 있다고 가정해도 된다. 팀에도 새로운 팀원이 합류할 수도 있고 작성자 본인이 다른 팀으로 떠나갈 수도 있으니 구현 주석도 체계적으로 작성해두는 편이 안전하다.
- 구글에서는 거의 모든 코드 파일에 파일 주석이 적혀있어야 한다.
- 일반적으로 파일 주석에서는 파일에 담겨 있는 내용을 요약해줘야 한다. 해당 코드의 주요 쓰임새와 어떤 독자를 의도하고 만든 코드인지를 명시한다.
- 한두 문단으로 간결하게 설명할 수 없는 API라면 충분히 사려 깊게 설계되지 않은 API일 수 있다는 신호이다. 이런 경우라면 API를 여러 조각으로 쪼개는 방안을 고려해보는 것이 좋다.
// -----------------------------------------------------------------------------
// str_cat.h
// -----------------------------------------------------------------------------
//
// This header file contains functions for efficiently concatenating and appending
// strings: StrCat() and StrAppend(). Most of the work within these routines is
// actually handled through use of a special AlphaNum type, which was designed
// to be used as a parameter type that efficiently manages conversion to
// strings and avoids copies in the above operations.
…- 현대적 언어들은 대부분 객체지향을 지원한다. 따라서 클래스 주석은 코드베이스에서 사용되는 API 객체들을 정의하는 중요한 주석이다.
- 구글에서는 모든 공개 클래스와 구조체는 클래스 주석을 담고 있어야 한다.
- 클래스 주석에서는 해당 클래스와 구조체의 목적과 주요 메서드들을 설명한다.
- 클래스 주석은 보통 객체임을 부각하기 위해 클래스 자신을 문장의 주어로 두고 어떻게 동작하는지를 설명하는 형태로 작성한다.
- Foo 클래스는 x, y, z 프로퍼티를 가지며, A라는 메서드를 제공하고, 다음과 같이 B라는 측면을 지니고 있습니다.
// -----------------------------------------------------------------------------
// AlphaNum
// -----------------------------------------------------------------------------
//
// The AlphaNum class acts as the main parameter type for StrCat() and
// StrAppend(), providing efficient conversion of numeric, boolean, and
// hexadecimal values (through the Hex type) into strings.- 구글에서는 자유 함수(free function)나 클래스의 공개 메서드에는 무조건 함수가 무슨 일을 하는지를 설명하는 함수 주석이 있어야 한다.
- 함수 주석은 함수가 무슨 동작을 하고 무엇을 반환하는지를 설명하며, 능동성을 부각하기 위해 동사로 시작해야 한다.
// StrCat()
//
// Merges the given strings or numbers, using no delimiter(s),
// returning the merged result as a string.
…- 함수 주석에서 'returns', 'throws'같은 다양한 상용구를 요구하는 경우도 있지만, 꼭 필요하지 않다고 판단했다. 실제로 인위적으로 섹션을 구분하지 않고 하나의 문장으로 표현하는 게 더 명확한 경우가 많다.
// Creates a new record for a customer with the given name and address,
// and returns the record ID, or throws `DuplicateEntryError` if a
// record with that name already exists.
int AddCustomer(string name, string address);- 구글의 팀 대부분은 중요한 프로젝트에 착수하기 전에 설계 문서부터 승인받아야 한다. 소프트웨어 엔지니어들은 일반적으로 팀에서 승인한 특정 템플릿을 이용해서 설계 문서 초안을 작성한다.
- 설계문서 작성은 엔지니어가 새 시스템을 배포하기 전에 첫 번째로 수행해야 하는 일이기에 다양한 문제를 고려해보기에 적절한 시간이다.
- 보안, 국제화, 스토리지 요구사항, 개인정보 보호 등. 대부분의 경우 각 도메인의 전문가들이 검토해준다.
- 좋은 설계 문서라면 설계의 목표와 구현 전략을 설명하고 설계상의 핵심 선택들과 관련한 트레이드오프를 명시해야 한다. 즉, 설계 목표를 제시하고 대안이 될 수 있는 설계들의 장점과 단점까지 함께 기술해줘야 한다.
- 새로운 팀에 합류한 엔지니어라면 누구라도 가능한 한 빠르게 개발 속도를 끌어올리고 싶어 할 것이다. 그래서 프로젝트 환경을 새로 구축하는 과정을 담은 튜토리얼이 아주 중요하다.
- 새로운 튜토리얼을 쓰기에 가장 적합한 시점은 누군가가 팀에 새로 합류했을 때이다.
- 텍스트 편집기를 열어두고 튜토리얼을 따라 하면서 수행해야 하는 모든 것을 적어본다. 도메인 지식이나 특별한 설정 제약은 없다고 가정한다.
- 독자가 수행해야 하는 모든 단계 각각에 번호를 붙인다. 단, 독자의 행위에 대응하는 시스템 동작에는 번호를 달지 않는다.
- http://example.com 서버에서 패키지를 다운로드합니다.
- 셸 스크립트를 홈 디렉터리에 복사합니다.
- 셸 스크립트를 실행합니다.
- 이제 foobar 시스템이 인증 시스템과 통신할 것입니다.
- 인증이 완료되면 foobar가 baz라는 새 데이터베이스를 실행시킬 것입니다.
- 명령줄에서 SQL 명령으로 baz가 실행되는지 확인해보세요.
CREATE DATABASE my_foobar_db;를 입력합니다.
- 이 절차에서 4, 5 단계는 서버에서 이루어진다. 설령 아무것도 하지 않아도 되더라도 독자가 무엇을 해야하는 지가 불분명하기 때문에 이러한 부수효과는 3단계에서 부연하는 게 타당하다.
- 독자가 한 번에 수행하는 작업은 하나의 단계에서 설명하여 각 단계에서 할 일을 헷갈리지 않도록 해야 한다.
- 독자가 눈으로 확인할 수 있는 입력이나 출력이 있다면 별도의 줄에 명시해주는 게 좋다.
- http://example.com 서버에서 패키지를 다운로드합니다.
$ curl -I http://example.com- 셸 스크립트를 홈 디렉터리에 복사합니다.
$ cp foobar.sh ~- 홈 디렉터리에서 셸 스크립트를 실행합니다.
$ cd~; foobar.sh이제 foobar 시스템이 인증 시스템과 통신할 것입니다. 인증이 완료되면 foobar가 baz라는 새 데이터베이스를 구동한 다음 사용자가 명령을 입력할 수 있는 셸을 띄울 것입니다.
- 명령줄에서 다음 SQL 명령을 실행하여 baz가 제대로 동작하는지 확인합니다.
baz:$ CREATE DATABASE my_foobar_db;- 어떤 코드는 코드 주석 같은 참조용 문서자료만으로는 부족하여 깊이 있는 설명을 곁들여야 한다. 이럴 때는 대체로 해당 API나 시스템의 개요를 알려주는 개념 문서를 첨부한다.
- 참조 문서자료와 달리 개념 문서는 벌어질 수 있는 모든 상황을 다 설명하지 않아도 된다. 개념을 더 명확하게 전달하는 게 목적이라서 정확성을 다소 희생할 수 있다는 뜻이다. 이 문서들의 핵심 목표는 독자를 이해시키는 것이다.
- 코드 주석을 문서자료계의 단위 테스트에 비유한다면, 개념 문서는 통합 테스트에 해당한다.
- 팀 페이지의 랜딩 페이지(첫 화면)는 정돈되지 않은 경우가 많다.
- 랜딩 페이지가 교통경찰 이상의 일을 한다면 제 역할을 못하고 있다는 신호이다.
- 랜딩 페이지에 링크가 너무 많다면 절을 구분해서 페이지를 분류별로 분할하는 게 좋다.
- 구글에서는 문서자료 역시 리뷰를 거쳐야 한다.
- 기술 문서 리뷰에 효과적인 방식
- 정확성 확인용 기술 리뷰: 주로 해당 주제 전문가가 수행하며, 팀 동료인 경우가 많다. 코드 리뷰 과정에서 함께 다루곤 한다.
- 명확성 확인용 독자 리뷰: 주로 도메인을 잘 모르는 사람이 수행한다. 팀에 새로 합류한 동료나 해당 API의 고객이다.
- 일관성 확인용 작문 리뷰: 주로 테크니컬 라이터나 자원자가 수행한다.
- 단 한 명뿐이라도 글을 봐주는 게 낫다. 모든 리뷰를 정식 프로세스를 밟아 진행할 필요도 없다.
- 대부분의 기술 문서자료는 어떻게(HOW)에 대한 답을 제시한다. 그 결과 다른 질문들(누가, 무엇을, 언제, 어디서, 왜)을 잊는 경향이 생겼다.
- 어떤 문서든 처음 두 문단이 끝나기 전에 다음 질문들에 답하도록 시도한다.
- 누가는 독자다. 하지만 대상 독자가 누구인지를 문서 안에서 명확하게 밝혀줘야 할 때도 있다. 예컨대 'Secret Wizard 프로젝트에 새로 합류한 엔지니어를 위한 문서입니다'와 같은 경우.
- 무엇은 문서의 목적을 알려준다. '이 문서는 Frobber 서버를 테스트 환경에서 구동하기 위해 설계된 튜토리얼입니다'와 같은 경우. 때로는 '무엇'을 작성하는 것만으로 문서를 적절하게 구성하는 데 도움이 된다. 예를 들어 '무엇'과 연관이 없는 정보가 적혀 있다면 해당 내용을 별도 문서로 옮기라는 신호이다.
- 언제는 문서가 생성되고, 리뷰되고, 갱신된 날짜를 이른다. 소스 코드에 임베드된 문서자료는 날짜 정보가 묵싲거으로 들어간다. 다른 형태의 문서자료들도 게시될 때 이 정보가 자동으로 추가되기도 한다. 만약 자동화된 시스템이 없다면 문서 자체에 작성일(혹은 최종 갱신일)을 기입한다.
- 어디에는 문서가 존재해야 할 장소를 말해주며, 역시 묵시적으로 결정되는 경우가 많다. 보통 설정과 관련된 정보는 버전 관리 시스템으로, 이상적으로는 문서자료가 설명하는 소스 코드와 함께 관리한다. 그 외 목적의 정보는 다른 포맷의 문서를 이용한다. 예를 들어 구글에서는 특히 설계와 관련한 문제는 구글 문서를 애용한다. 하지만 어느 시점부터 공유 문서의 주 용도는 논의보다는 안정된 버전 기록쪽으로 치우치기 시작한다. 그 시점이 되면 더 안정적이고, 소유권도 명확하고, 버전 관리도 잘 되는 다른 시스템으로 옮기는 게 좋다.
- 왜는 문서의 목적을 이른다. 문서를 읽은 독자가 무엇을 얻어가기를 바라는지를 요약한다. 경험상 '왜'는 문서의 소개 부분에 명시하는 게 좋다. 그러면 마지막에 요약을 작성할 때 '왜'를 기초로 원래 기대한 바를 달성했는지를 확인하고 달성하도록 보강할 수 있다.
- 모든 문서는 시작, 중간, 끝이 있다. 대부분의 문서에는 최소 이 세 부분이 포함되어야 한다.
- 문서자료에서는 중복이 때로 유용하다. 핵심이 텍스트 더미에 묻혀 있다면 기억하거나 찾아내기 어려울 수 있다. 너무 일찍 부각하면 이어지는 맥락 정보들을 놓칠 수 있다.
- 일반적인 해법은 각 절의 도입 단락에서 핵심을 요약해 알려준 후, 해당 절의 나머지에서 구체적으로 사례를 설명하는 방법이다.
- 완전성(completeness), 정확성(accuracy), 명확성(clarity)
- 세 특징을 모두 담기는 어렵다. 예컨대 문서를 더 완벽하게 만들려다 보면 명확성이 떨어지기 쉽다. 일어날 수 있는 모든 상황을 완벽하고 정확하게 작성하면 명확성에 영향을 준다. 다른 문서에서도 복잡한 주제를 명확하게 설명하려다 보면 정확성이 떨어질 수 있다.
- 개념 문서라면 드물게 발생하는 부수효과는 일부러 언급하지 않기도 하는데, 이는 의도한 모든 행위를 융통성 없이 소개하는 게 아니라 독자가 API 사용법에 익숙해지게 해주는 것이기 때문이다.
- 좋은 문서란 의도한 역할을 잘 수행하는 문서이다.
- 개념 문서를 작성한다면 API의 모든 측면을 전부 다룰 필요는 없다.
- 참조 문서를 작성한다면 완전하지만 명확성은 다소 떨어지는 문서가 적합하다.
- 랜딩 페이지를 작성한다면 구성에 집중하고 논의사항은 최소가 되도록 관리한다.
- 문서의 품질을 빠르게 개선하는 방법은 독자가 필요로하는 게 무엇인지에 집중하는 것이다.
- 문서를 버리는 일은 되도록 생기지 않도록 노력해야 한다. 하지만 문서가 본래의 목적을 더 이상 수행할 수 없다면 폐기하거나 폐기 대상으로 표시해줘야 한다(가능하면 최신 정보의 위치를 알려준다).
- 구글은 문서자료에 신선도 보증 기간(freshness date)를 붙인다. 마지막으로 리뷰한 날짜를 기록해두면 이 메타데이터를 활용하여 가령 3개월 동안 갱신되지 않을 시 알림 메일을 보내는 식이다.
<!--*
# Document freshness: For more information, see go/fresh-source.
freshness: { owner: `username` reviewed: '2019-02-27' }
*-->
- 구글은 엔지니어링팀 대다수가 팀에 필요한 문서자료를 스스로 완벽하게 작성할 수 있음을 깨달았다. 팀 안에서는 피드백 루프가 아주 기민하고, 도메인 지식과 가정도 명확하며, 무엇을 요구하는지도 더 분명하기 때문이다.
- 다른 이의 도움이 필요한 경우는 오직 팀원 외 독자를 위한 문서를 작성할 때 뿐이었다.
- 테크니컬 라이터는 희소하기 때문에 소프트웨어 엔지니어들이 일반적인 업무로 취급하지 않는 일에 집중해야 한다. 예컨데 API 경계를 넘나드는 문서 작성이 여기에 속한다.
- 엔지니어링 문서자료의 품질을 개선하려면 엔지니어들과 전체 엔지니어링 조직이 내가 곧 문제이자 해결책임을 깨우쳐야 한다.
- 문서에서 손을 놓고 포기하지 말고, 양질의 문서자료를 생산하는 일 역시 내게 맡겨진 과업이며 장기적으로 시간과 노력을 절약해준다는 사실을 깨달아야 한다.
- 문서자료는 시간이 흐르고 조직 규모가 커질수록 더 중요해진다.
- 문서자료 변경도 기존 개발자 워크플로에 통합되어야 한다.
- 하나의 문서는 하나의 목적에 집중해야 한다.
- 문서자료는 자신이 아니라 독자를 위해 써야 한다.