10. 문서자료
20 Feb 2023 | Software Engineering
10. 문서자료
- 구글에서 문서자료를 개선하고자 해본 시도 중 가장 성공적이었던 방법은 문서자료를 코드처럼 취급하여 엔지니어링 워크플로에 통합하는 것
10.1 문서자료란?
- 문서자료란 엔지니어가 작업을 끝마치기 위해 작성해야 하는 모든 부수적인 텍스트 (코드 주석 포함)
10.2 문서자료가 필요한 이유
- 다음 질문에 대해 답이 가능
- 이 설계를 택한 이유가 뭐지?
- 코드를 왜 이런 식으로 구현했을까?
- (예컨대 2년후 자신의 코드를 살펴보며) “내가” 왜 이렇게 구현했지?
- 문서자료의 이런 혜택에도 불구하고 엔지니어들이 “덜 중요하게” 생각하는 이유는?
- 만흥 ㄴ엔지니어가 글쓰기를 프로그래밍과는 별개의 기술로 봄
- 글쓰기에 자신 없어함
- 문서자료는 도구 지원이나 개발 워크플로 통합 측면에서 아직 많이 부족하기 때문에 작성하기가 상대적으로 어려움
- 문서자료가 기존 코드를 유지보수하기 더 쉽게 해준다고 생각하기보다는 유지보수할 대상이 하나 더 늘어난다고 생각
- 문서자료는 다양한 부류의 사람에게 혜택을 줌, 심지어 작성자에게도
- API를 가다듬는데 도움을 줌. 글을 써보면서 설계를 다시 되돌아 볼 수 있음
- 유지보수를 위한 로드맵과 과거 이력을 제공
- 코드를 더 전문적이고 매력 있어 보이게 함. 개발자들은 무의식적으로 문서화가 잘되어 있는 API를 더 잘 설계된 것이라고 여김
- 이용자의 질문이 줄어듬
10.3 문서자료는 코드와 같다
- 구글에는 문서자료용 스타일 가이드도 있음
- 꼭 따라야 하는 내부 정책과 규칙이 있어야 함
- 버전 관리 시스템에 등록해 관리해야 합니다.
- 관리 책임자를 명시해야 합니다.
- 변경 시 (문서자료가 설명하는 코드와 함께) 리뷰를 거쳐야 합니다.
- 코드상의 버그를 추적하듯 문제를 추적해야 합니다.
- 주기적으로 평가 (혹은 테스트)를 받아야 합니다.
- 가능하다면 정확성이나 최신 정보 반영 여부 등을 측정해야 합니다. (아쉽게도 아직은 도구들이 충분히 뒷받침해주지 못합니다.)
10.4 독자를 알자
- 독자 유형
- 경험 수준: 건문 프로그래머, 혹은 프로그래밍 언어조차 낯선 초보 엔지니어
- 도메인 지식: 팀원, 혹은 최종 API 정도에만 친숙한 사내의 다른 엔지니어
- 목적: 여러분이 제공하는 API를 사용해 특정 작업을 수행하거나 급히 정보를 얻어내야하는 최종 사용자, 혹은 아무에게도 유지보수를 맡기고 싶지 않을 만큼 꼬여있는 특정 구현마저 기꺼이 책임지려 하는 소프트웨어 전문가
- 문서를 접하게 되는 방식
- 탐색자 : 자신이 원하는 것을 정확히 알고, 읽고 있는 문서자료가 원하는 정보를 담고 있는지를 알고 싶어하는 엔지니어 -> 일관성이 핵심
- 배회자 : 무엇을 원하는지를 정확하게 알지 못하는 사람 -> 명료한 글이 효과적
10.5 문서자료 유형
- 참조용 문서자료 (코드 주석 포함)
- C++ 헤더 파일을 API 설명 문서를 작성해두는 용도로 활용
- Javadoc, PyDoc, GoDoc…
- 파일 주석
- 클래스 주석
- 함수 주석 (Public Method)
- 설계 문서
- 표준 설계 문서 템플릿 - 보안, 국제화, 스토리지 요구사항, 개인정보 보호…
- 튜토리얼
- 독자가 수행해야 하는 모든 단계 각각에 번호를 붙여야 함
- 모든 단계에서 독자가 특정한 일을 수행해야 함
- 개념 설명 문서자료
- 랜딩 페이지
10.6 문서라죠 리뷰
- 정확성 확인용 기술 리뷰 : 주로 해당 주제 전문가가 수행하며, 팀 동료인 경우가 많습니다. 코드 리뷰 과정에서 함께 다루곤 합니다.
- 명확성 확인용 독자 리뷰 : 주로 도메인을 잘 모르는 사람이 수행합니다. 팀에 새로 합류한 동료나 해당 API의 고객일 것입니다.
- 일관성 확인용 작문 리뷰 : 주로 테크니컬 라이터나 자원자가 수행
10.7 문서화 철학
- 누가, 무엇을, 언제, 어디서, 왜
- 시작, 중간, 끝
- 좋은 문서자료의 특징
- 완전성, 정확성, 명확성
- 문서 폐기하기
- 문서에 신선도 보증 기간 붙이기
10.8 테크니컬 라이터가 필요한 순간
- 팀에 필요한 문서자료는 엔지니어가 충분히 작성 가능
- API 경계를 넘나드는 문서 작성이 테크니컬 라이터가 필요
핵심 정리
- 문서자료는 시간이 흐르고 조직 규모가 커질수록 더 중요해집니다.
- 문서자료 변경도 기존 개발자 워크플로에 통합되어야 합니다.
- 하나의 문서는 하나의 목적에 집중해야 합니다.
- 문서자료는 자신이 아니라 독자를 위해 써야 합니다.
10. 문서자료
- 구글에서 문서자료를 개선하고자 해본 시도 중 가장 성공적이었던 방법은 문서자료를 코드처럼 취급하여 엔지니어링 워크플로에 통합하는 것
10.1 문서자료란?
- 문서자료란 엔지니어가 작업을 끝마치기 위해 작성해야 하는 모든 부수적인 텍스트 (코드 주석 포함)
10.2 문서자료가 필요한 이유
- 다음 질문에 대해 답이 가능
- 이 설계를 택한 이유가 뭐지?
- 코드를 왜 이런 식으로 구현했을까?
- (예컨대 2년후 자신의 코드를 살펴보며) “내가” 왜 이렇게 구현했지?
- 문서자료의 이런 혜택에도 불구하고 엔지니어들이 “덜 중요하게” 생각하는 이유는?
- 만흥 ㄴ엔지니어가 글쓰기를 프로그래밍과는 별개의 기술로 봄
- 글쓰기에 자신 없어함
- 문서자료는 도구 지원이나 개발 워크플로 통합 측면에서 아직 많이 부족하기 때문에 작성하기가 상대적으로 어려움
- 문서자료가 기존 코드를 유지보수하기 더 쉽게 해준다고 생각하기보다는 유지보수할 대상이 하나 더 늘어난다고 생각
- 문서자료는 다양한 부류의 사람에게 혜택을 줌, 심지어 작성자에게도
- API를 가다듬는데 도움을 줌. 글을 써보면서 설계를 다시 되돌아 볼 수 있음
- 유지보수를 위한 로드맵과 과거 이력을 제공
- 코드를 더 전문적이고 매력 있어 보이게 함. 개발자들은 무의식적으로 문서화가 잘되어 있는 API를 더 잘 설계된 것이라고 여김
- 이용자의 질문이 줄어듬
10.3 문서자료는 코드와 같다
- 구글에는 문서자료용 스타일 가이드도 있음
- 꼭 따라야 하는 내부 정책과 규칙이 있어야 함
- 버전 관리 시스템에 등록해 관리해야 합니다.
- 관리 책임자를 명시해야 합니다.
- 변경 시 (문서자료가 설명하는 코드와 함께) 리뷰를 거쳐야 합니다.
- 코드상의 버그를 추적하듯 문제를 추적해야 합니다.
- 주기적으로 평가 (혹은 테스트)를 받아야 합니다.
- 가능하다면 정확성이나 최신 정보 반영 여부 등을 측정해야 합니다. (아쉽게도 아직은 도구들이 충분히 뒷받침해주지 못합니다.)
10.4 독자를 알자
- 독자 유형
- 경험 수준: 건문 프로그래머, 혹은 프로그래밍 언어조차 낯선 초보 엔지니어
- 도메인 지식: 팀원, 혹은 최종 API 정도에만 친숙한 사내의 다른 엔지니어
- 목적: 여러분이 제공하는 API를 사용해 특정 작업을 수행하거나 급히 정보를 얻어내야하는 최종 사용자, 혹은 아무에게도 유지보수를 맡기고 싶지 않을 만큼 꼬여있는 특정 구현마저 기꺼이 책임지려 하는 소프트웨어 전문가
- 문서를 접하게 되는 방식
- 탐색자 : 자신이 원하는 것을 정확히 알고, 읽고 있는 문서자료가 원하는 정보를 담고 있는지를 알고 싶어하는 엔지니어 -> 일관성이 핵심
- 배회자 : 무엇을 원하는지를 정확하게 알지 못하는 사람 -> 명료한 글이 효과적
10.5 문서자료 유형
- 참조용 문서자료 (코드 주석 포함)
- C++ 헤더 파일을 API 설명 문서를 작성해두는 용도로 활용
- Javadoc, PyDoc, GoDoc…
- 파일 주석
- 클래스 주석
- 함수 주석 (Public Method)
- 설계 문서
- 표준 설계 문서 템플릿 - 보안, 국제화, 스토리지 요구사항, 개인정보 보호…
- 튜토리얼
- 독자가 수행해야 하는 모든 단계 각각에 번호를 붙여야 함
- 모든 단계에서 독자가 특정한 일을 수행해야 함
- 개념 설명 문서자료
- 랜딩 페이지
10.6 문서라죠 리뷰
- 정확성 확인용 기술 리뷰 : 주로 해당 주제 전문가가 수행하며, 팀 동료인 경우가 많습니다. 코드 리뷰 과정에서 함께 다루곤 합니다.
- 명확성 확인용 독자 리뷰 : 주로 도메인을 잘 모르는 사람이 수행합니다. 팀에 새로 합류한 동료나 해당 API의 고객일 것입니다.
- 일관성 확인용 작문 리뷰 : 주로 테크니컬 라이터나 자원자가 수행
10.7 문서화 철학
- 누가, 무엇을, 언제, 어디서, 왜
- 시작, 중간, 끝
- 좋은 문서자료의 특징
- 완전성, 정확성, 명확성
- 문서 폐기하기
- 문서에 신선도 보증 기간 붙이기
10.8 테크니컬 라이터가 필요한 순간
- 팀에 필요한 문서자료는 엔지니어가 충분히 작성 가능
- API 경계를 넘나드는 문서 작성이 테크니컬 라이터가 필요
핵심 정리
- 문서자료는 시간이 흐르고 조직 규모가 커질수록 더 중요해집니다.
- 문서자료 변경도 기존 개발자 워크플로에 통합되어야 합니다.
- 하나의 문서는 하나의 목적에 집중해야 합니다.
- 문서자료는 자신이 아니라 독자를 위해 써야 합니다.
Comments