TOC
참고
본 내용은 구글 엔지니어는 이렇게 일한다(링크)를 읽고 정리한 내용입니다.
책의 내용과 함께 개인적인 의견과 생각, 학습을 담아 작성하였습니다.
들어가며
- 현실적으로 대부분의 문서자료는 소프트웨어 엔지니어 스스로 작성해야 한다.
- 엔지니어가 문서화를 효과적으로 할 수 있도록 도와주는 적절한 도구와 보상이 필요하다.
- 문서자료를 코드처럼 취급하여 엔지니어링 워크플로에 통합하는 것이 가장 효과적인 경험
글만 써도 돈을 주는 컨텐츠 마케터가 부럽기도 했습니다. 저도 문서화를 할 때 보상이 떨어지면 좋겠네요... 지금은 필요하니까~ 라고 생각하며 하고 있습니다.
문서자료가 필요한 이유
- 문서자료: 엔지니어가 작업을 끝마치기 위해 작성해야 하는 모든 부수적인 텍스트
- 자신과 팀의 목표가 활자로 명확하게 적혀있을 때 역량을 더 집중하게 된다.
- 보통 작성자에게는 즉각적인 이득이 없다. (문서화는 보통 선제적인 투자)
- 한 번만 작성해도 수백, 수천 번 읽히게 된다. 초기 비용은 미래의 모든 독자에게 혜택으로 돌아간다.
- 문서화는 다양한 부류의 사람에게 혜택을 준다. 심지어 작성자에게도.
- 문서를 잘 작성하는 데 쏟은 노력은 시간이 지날수록 배가 되어 돌아온다.
- 문서자료는 세월이 흐를수록 더 중요해진다. 특히 핵심 코드를 잘 문서화하라.
- 문서화는 어려우니 문서자료를 보다 더 쉽게 작성할 수 있도록 도와주는 방법을 생각하라.
사내에서도 당장 필요하지 않은 문서 자료들을 스스로 많이 적고 있습니다. 제가 갑자기 사라지면 아무도 개발적인 히스토리를 알지 못할테니까요. 원래는 GitLab에서 Issue와 Merge Request를 열심히 작성했는데, 최근 GitHub으로 마이그레이션을 시도하며 방법을 열심히 찾고 있습니다.
문서자료는 코드와 같다
- 문서 쓰기는 코드 작성과 크게 다르지 않다. 일관되어야 하고, 명확해야 하고, 오류를 피해야 한다.
- 버전 관리를 해야 한다. 소유자가 명확해야 한다. 변경이 추적 가능해야 한다.
공감합니다. 문서 작성도 코드 관리처럼 되면 유지보수가 되어야 하겠지만, 그래야 문서가 썪지 않고 제 역할을 하겠죠. 한편 개발자가 코드에 대한 애정, 그리고 관리 책임이 있는 것처럼 문서도 아끼게 될 수 있다는 장점이 큰 것 같습니다. 저도 개발자지만 역시 개발자는 단순하네요.
독자를 알자
- 문서자료 작성의 가장 중요한 실수는 "자신만을 위해 쓴다"라는 것
- 문서자료로 만족시켜야 할 독자가 누구인지를 알아내야 한다.
- 설계 문서: 의사결정권자들을 설득
- 튜토리얼: 코드베이스에 익숙하지 않은 사람들을 위해 명확한 지시
- API: API 사용자 모두를 위해 완벽하고 정확한 참고 정보 제공
독자 유형
- 어느 기준으로 보느냐에 따라 여러 성격의 독자가 있을 수 있다.
- 경험 수준: 전문/초보 프로그래머
- 도메인 지식: 팀원, 혹은 사내의 다른 엔지니어
- 목적
- 모든 독자에게 적합한 방식으로 쓰는 것이 좋다.
- 때문에 문저 작성의 핵심은 균형을 잘 잡는 것
- 문서를 "짧게" 쓰는 게 유리하다.
- 복잡한 주제라면 초심자를 위해 충분히 설명하되, 전문가를 짜증나게 하지 말 것
- 모든 정보를 담아 글을 쓰고 간명하게 편집하고 중복 내용을 삭제하라.
- 문서를 짧고 명확하게 관리한다면 모두를 만족시킬 수 있다.
저는 글을 쓸 때도 자세히 쓰는 게 좋다고 생각했는데, 어쩌면 투머치였을 수도 있겠습니다... 주절주절 말고 요약해서 핵심만 쓰기를 연습해야 하겠습니다.
문서자료 유형
- 문서의 종류가 다름을 알고 서로 '섞이지 않도록' 하라.
- 하나의 문서는 하나의 목적에 집중해야 한다. 논리적인 조각으로 나눠라.
블로그 글 쓸 때 조금 길어진다 싶긴 했는데, 그렇다고 한 포스팅이 너무 짧은 것도 싫더라고요.. 그래도 주제를 나눠서 더 짧게 쓰는 게 나을려나 싶네요.
참조용 문서자료
- 코드베이스에 속한 코드의 사용법을 설명하는 문서
- 대표적인 예: 코드 주석. API 주석과 구현 주석으로 나눈다.
- '좋은 주석'이란 뭘까?
파일 주석
- 파일에 담겨있는 내용을 요약
- 주요 쓰임새와 어떤 독자를 의도하고 만든 코드인지
- 한 두 문단으로 간결하게 설명할 수 없다면 제대로 설계되지 않은 것
함수 주석
- 함수가 무슨 일을 하는지 설명하는 주석
- 능동성을 부각하기 위해 동사로 시작
그러는 한편, 함수의 이름이 내용을 충분히 담도록 하여 주석조차 쓰지 않는 것도 많이 봤습니다. 동사로 시작한다거나, 하는 것들은 충분히 함수명에 녹여낼 수 있으니까요. 개인적으로는 formatting하는 함수에서는 주석을 많이 달아주는 편입니다. 특히 date 관련이요. (요새는 dayjs 등의 라이브러리로 바로 포맷팅해서 불필요한 것도 같지만요.)
설계 문서
- 코딩 시작 전에 진행하는 코드 리뷰
- 다양한 문제를 고려해보기 적절한 시간
- 보안, 국제화, 스토리지 요구사항, 개인정보 보호 등
- 설계의 목표와 구현 전략을 설명, 설계상의 핵심 선택들과 관련한 트레이드오프 명시
튜토리얼
- 새로운 튜토리얼을 쓰기에 가장 적합한 시점은 누군가 새로 팀에 합류했을 때
- 프로젝트 환경을 구축하고 실행하는 방법 작성
- 이때 도메인 지식이나 특별한 설정 제약은 없다고 가정
개념 설명 문서
- 코드 주석 등의 참조용 문서로는 깊이가 부족한 경우 작성
- 유명 라이브러리의 소개 문서, 서버가 관리하는 데이터의 수명 주기 설명 문서
- 참조 문서자료를 보강하는 역할
- 벌어질 수 있는 모든 상황을 설명하지 않는다.
- 핵심 목표는 독자들을 이해시키는 것
- 코드 주석이 문서의 단위 테스트라면 개념 문서는 통합 테스트에 해당
- 전문가에서 초보자까지 많은 독자에게 유익해야 한다.
문서자료 리뷰
정확성확인용 기술 리뷰: 해당 주제 전문가가 수행, 보통 팀 동료, 코드 리뷰 과정에서 함께 취급명확성확인용 독자 리뷰: 주로 도메인을 잘 모르는 사람이 수행, 팀에 새로 합류한 동료나 API의 고객일관성확인용 작문 리뷰: 주로 테크니컬 라이터나 자원자가 수행
중요한 점은 문서화가 워크플로에 녹아 있다면 문서자료의 품질이 점차 개선된다는 사실
문서화 철학
이번 절은 구글에서의 사실이 아닌, 저자의 개인 의견임을 강하게 밝히고 시작했다. 이해하면 기술 문서 작성에 도움이 되지만 반드시 알아야 하는 것은 아닌 사실
누가, 무엇을, 언제, 어디서, 왜
- 대부분의 기술 문서자료는 '어떻게'에 대한 답을 제시한다.
- 나머지 질문들이 '어떻게'만큼 중요하진 않지만 틀을 구성하지 않으면 혼란스러워진다.
- 처음 두 문단이 끝나기 전에 다음 질문들에 답하도록 구성해보자.
누가: 대상 독자가 누구인지무엇: 문서의 내용언제: 문서의 생성, 리뷰, 갱신 날짜어디: 문서가 존재해야 할 장소왜: 문서의 목적
블로그 포스팅을 할 때, 암묵적으로 결정되는 '언제'와 '어디', '누가'를 제외하고는 최대한 글에 무엇을, 어떻게, 왜는 많이 녹여내려 했습니다. 다음은 '누가'를 빠르게 명시해줘도 좋겠다는 생각이 드네요. '언제'는 시스템적으로 들어가고 '어디'는 제가 결정하기 때문에 예상 독자를 잘 생각하며 글을 써야 겠습니다.
좋은 문서자료의 특징
- 좋은 문서자료는 세 가지 특징이 있다.
완전성,정확성,명확성 - 단, 하나의 문서에 셋을 다 담긴 어렵다. 문서를 완벽하게 만들려다 보면 명확성이 떨어진다.
- '좋은 문서'란 의도한 역할을 잘 수행하는 문서
- API 문서에 설계 결정이나 상세 구현 내용까지 설명하는 실수를 하지 말라.
- 설계 결정이 필요하다면 해당 목적에 특화된 문서에 '분리해서' 작성하라.
문서 폐기하기
- 오래된 문서는 문제를 일으킨다.
- 문서가 본래의 목적을 더 이상 수행할 수 없다면 폐기하거나 '폐기 대상'으로 표시해줘야 한다.
- 구글에서는 문서의 '신선도 보증기간' 제도를 운영하여 문서가 상하지 않도록 신경쓴다.
테크니컬 라이터가 필요한 순간
- 테크니컬 라이터는 도메인에 익숙하지 않은 사람을 더 잘 대변할 수 있다.
- 프로젝트가 어디에 유용한가에 관한 팀 내 가정에 의문을 품어보는 것이 핵심 역할
총평
저는 지금 혼자 개발자로서 팀에 있고, 코드베이스에 코드도 혼자 녹여내고 있지만, 저는 미래를 위해 라이브러리, 기술스택의 선택이나 작업 단위의 작업 배경, 작업부분을 최대한 기록하려고 합니다. Pull Request 작성에도 힘을 쓰고 있어요. 이전에 나왔던 버스 지수처럼 제가 버스에 치여 누군가 제 일을 대신 맡게 될 때, 히스토리가 남아있지 않다면 저의 부재는 크게 다가갈 수 있으니까요. 저는 한 명이기 때문에 더 열심히 남기고 적어야 합니다.
이번 장은 그런 문서자료의 작성에 대한 가치, 노하우, 철학을 잘 설명해주고 있습니다. 저 역시 문서화를 하며 조금은 현재가 아닌 미래에 투자하는 노력을 쏟고 있으나, 역시나 비개발자인 팀 동료와 리더들은 크게 알아주는 작업은 아닙니다. 당장의 퍼포먼스에는 도움이 되지 않으니까요. 그런 제 상황에 응원을 해주는 느낌이었습니다. 앞으로도... 저의 부재나 동료의 합류에 대비할 수 있도록 문서화를 열심히 이어나가보겠습니다.
