문서자료를 코드로 취급하기

  • 일단 이들은 문서자료를 코드로 취급하면서 문서를 유지보수하는 일이 수월해졌다고 하네.
  • 그리고 문서자료는 아래와 같은 취급을 꼭 해야한대.
    • 꼭 따라야 하는 내부 정책과 규칙이 있어야 한다.
    • 버전 관리 시스템에 등록해 관리해야 한다.
    • 관리 책임자를 명시해야 한다.
    • 변경 시 (문서자료가 설명하는 코드와 함께) 리뷰를 거쳐야 한다.
    • 코드 상 버그를 추적하든 문제를 추적해야 한다.
    • 주기적으로 평가(혹은 테스트)를 받아야 한다.
    • 가능하다면 정확성이나 최신 정보 반영 여부 등을 측정해야 한다.

독자 유형

  • 경험 수준: 전문 프로그래머, 혹은 프로그래밍 언어 조차 낯선 초보 엔지니어
  • 도메인 지식: 팀원, 혹은 최종 API 정도에만 친숙한 사내의 다른 엔지니어
  • 목적: 여러분이 제공하는 API를 사용해 특정 작업을 수행하거나 급히 정보를 얻어내야 하는 최종 사용자. 혹은 아무에게도 유지보수를 맡기고 싶지 않을 만큼 꼬여 있는 특정 구현마저 기꺼이 책임지려 하는 소프트웨어 전문가
  • 탐색자: 자신이 원하는 것을 정확히 알고, 읽고 있는 문서자료가 원하는 정보를 담고있는지 알고싶어하는 엔지니어. 일관성이 핵심
  • 배회자: 무엇을 원하는지 알지 못하는 사람. 아이디어만 가지고 있을 것. 명료한 글이 효과적

문서자료 유형

  • 참조용 문서자료(코드주석 포함)
    • 파일 주석(구글은 거의 모든 파일에 주석이 적혀있어야 함): 파일에 담겨있는 내용 요약
    • 클래스 주석: 코드베이스에서 사용되는 API 객체들을 정의하는 중요한 주석
    • 함수 주석: 함수가 무슨 일을 하는지를 설명하는 주석. 무슨 동작을 하고 무엇을 반환하는지 설명. 능동성을 부각하기 위해 동사로 시작(영어)
  • 설계 문서
    • 특정 템플릿을 이용해 설계 문서 초안을 작성함. 엔지니어가 새 시스템을 배포하기 전에 첫 번째로 수행하는 일임.
  • 튜토리얼(우리 상황에 꼭 필요)
    • 프로젝트 환경을 새로 구축하는 과정을 담은 튜토리얼이 아주 중요함.
    • Hello World는 모든 팀원이 올바른 첫 발을 내딛는 데 가장 좋은 방법 중 하나임.
    • 이 책에서는 나쁜 튜토리얼과 개선된 튜토리얼을 설명함. 필요하면 인터넷에서 찾아보는 것도 괜찮을 듯.
  • 개념 설명 문서자료
    • 주석 같은 참조용 자료만으로는 부족하여 깊이 있는 설명을 곁들여야 함.
    • API나 시스템의 개요를 알려주는 개념 문서를 첨부함. 대표적으로는 유명 라이브러리의 소개 문서나 서버가 관리하는 데이터의 수명 주기 설명 문서 등을 예로 들 수 있음.
    • 참조 문서 자료들을 대체하기보다는 보강하는 역할. 때로는 일부 정보가 중복되기도 하지만 더 명확하게 설명하기 위해 의도적으로 그렇게 하기도 함.
    • 모든 벌어질 상황을 다 설명하지 않아도 됨. 전문가부터 초보자까지 많은 독자에게 유익해야 함.
    • 명확성이 중요하므로 완전하지 않거나 때로는 정확성을 희생하곤 함.
  • 랜딩 페이지
    • 수정하기는 쉬움. 랜딩 페이지의 목적을 명확히 인식하고 자세한 정보는 모두 다른 페이지를 가리키는 링크로 대체하면 됨.
    • 교통경찰 이상의 역할을 한다면 제 역할을 못하고 있다는 신호임.

문서자료 리뷰

  • 정확성
  • 명확성
  • 일관성

문서화 철학

  • 누가, 무엇을, 언제, 어디서, 왜 - 어떻게만큼이나 왜가 중요하다. 대부분은 어떻게를 생각하겠지만, 의도적으로 다섯가지를 생각해보아야 함.
  • 시작, 중간, 끝 - 각 절의 도입 단락에서 핵심을 요약해 알려준 후, 해당 절의 나머지에서 구체적으로 사례를 설명하는 방법이 효과적임.
  • 좋은 문서자료 - 완전성, 정확성, 명확성. 의도한 역할을 잘 수행하는 문서가 좋은 문서. 문서 하나에 둘 이상의 역할을 맡기는 일은 거의 없다.
  • 문서 폐기 - 버리는 일은 되도록 생기면 안 되지만, 본래 목적을 더이상 수행할 수 없다면 폐기하거나 '폐기대상'으로 표시. 구글은 신선도 보증 기간을 붙여두곤 함. 3개월 동안 갱신되지 않으면 알림 메일 보내는 식임.