Part III 프로세스
CHAPTER 10 문서자료
대부분의 엔지니어가 코드를 작성하고 이용하고 유지보수 하면서 대표적인 불만이 양질의 문서자료가 부족하다는 점
구글에서 문서 자료를 개선하고자 해본 시도 중 가장 성공적이었던 방법은 문서자료를 코드처럼 취급하여 엔지니어링 워크플로에 통합하는 것
문서자료란?
엔지니어가 작업을 끝마치기 위해 작성해야 하는 모든 부수적인 테스트를 의미
문서자료가 필요한 이유
양질의 문서 자료는 엔지니어링 조직에 커다란 축복
코드와 API를 이해하기 쉬워지고 실수가 줄어든다
프로젝트팀은 자신들의 설계 목표와 팀의 목표가 활자로 명확하게 적혀있을 때 역량을 더 집중하게 됩니다.
수동으로 해야 되는 일은 절차가 잘 기술되어 있어야 쉬워진다.
문서자료가 중요한데 덜중요하다고 생각되는 이유가 무엇인가?
- 해택이 즉각적으로 돌어오지 않는다
- 글쓰르길 프로그래밍과는 별개의 기술로 본다
- 글쓰기에 자신 없어하는 엔지니어도 많다
- 문서자료는 도구 지원이나 개발 워크플로 통합 측면에서 아직 많이 부족하기 때문에 작성하기가 상대적으로 더 어렵다
- 문서자료가 기존 코드를 유지 보수하기 더 쉽게 해준다고 생각하기보다는 유지보수할 대상이 하나 더 늘어난다고 생각한다
문서자료는 다양한 부류에 사람에게 혜택을 준다
작성자에도 혜택을 받는다
- API를 가다듭는데 도움을 준다
- 유지보수를 위한 로드맵과 과거 이력을 제공한다
- 코드를 더 전문적이고 매력있게 보이게 한다
읽는이에게 최적화 하라
문서자료는 코드와 같다
- 꼭 따라야 하는 내부 정책과 규칙이 있어야 한다
- 버전 관리 시스템에 등록해 관리해야 한다
- 관리 책임자를 명시해야 한다
- 변경시 리뷰를 거쳐야 한다
- 주기적으로 평가를 받아야 한다
- 가능하면 정확성이나 최신 정보 반영 여부등을 측정해야 한다
독자를 알라
문서자료를 작성하면 법하는 가장 중요한 실수는 자신만을 위해 쓴다는것
독자 유형
- 도메인 지식을 독자의 눈높이에 맞는 기술 수준으로 써야한다
- 경험 수준 : 전문 프로그래머, 초보 엔지니어
- 도메인 지식 : 팀원, 혹은 다른 사내직원
- 목적 : 최종사용자, 소프트웨어 전문가
- 탐색자 : 자신이 원하는것을 명확히 알고 있는 사람
- 배외자 : 무엇을 원하는지 정확하게 알지 못하는 사람
문서자료 유형
- 참조용 문서자료
- 파일 주석
- 클래스 주석
- 함수주석
- 설계 문서
- 튜토리얼
- 개념 설명 문서
- 랜딩 페이지
문서자료 리뷰
- 정확성 확인용 기술 리뷰
- 명확성 확인용 기술 리뷰
- 일관성 확인용 기술 리뷰
문서화 철학
- 누가 무엇을 어떻게 어디서 왜
- 누갸 : 독자
- 무엇 : 문서의 목적
- 언제 : 생성되고 리뷰되고 갱신된 날짜
- 어디에 : 문서가 존재해야할 장소
- 왜 : 문서의 목적
- 시작 중간 끝
- 좋은 문서자료의 특징
- 완전성
- 정확성
- 명확성
- 문서 폐기하기
테크니컬 라이터가 필요한 순간
팀원 외 독자를 위한 문서를 만들때 필요하다
마치며
내가 곧 문제이자 해결책임