문서 작성 … 애써 외면해본다

개발 자체만큼이나 중요한 부분이 문서 작성이라는 것을 부정하는 개발자는 없다. 하지만 문서를 보고 문서를 작성한 개발자를 탓하고, 나의 동료를 탓하고, 더 나아가 과거에 그 문서를 작성했던 사람이 나 자신이었음을 깨닫고 소위 말하는 현자타임에 빠지는 경우를 자주 경험해봤을 것이다(나만 그런 건 아니지?). 성숙한 개발 조직이 아닐 수록, 이런 경우를 많이 맞닥뜨릴 때가 있다. 소수의머리로는 아는 사실을 마음은 애써 외면하는 걸까?

(1) 가이드라인 없거나, (2) 어떻게 작성해야할 지 막막하거나, (3) 사내에서 잘 작성된 문서라는 기준이 정해져있지 않거나, (4) 중요하다고 인식되지 않아 충분한 시간이 주어지지 않거나 시간을 들여도 인정 받기 어려워서 … 일 것이다. 이 모든 것이 전부 다 해당될 수도 있다.

Docs for Developers

한빛미디어에서 출간된 Docs for Developers 기술 문서 작성 완벽 가이드 는 제목 그대로 기술문서를 “제대로” 작성하기 위한 가이드를 담고 있다. 개인적으로 이 책의 처음 목차를 보았을 때, 내용이 탄탄할 것이라는 기대가 들었고, 실제로 책을 통해 기술 문서를 작성할 때 막막했던 부분들을에 대한 조언을 많이 받을 수 있었다.

Docs for Developer 기술문서 작성 완벽 가이드 (저자: 자레드 바티 외 4인)

Docs for Developer 기술문서 작성 완벽 가이드 (저자: 자레드 바티 외 4인)

내용 훑어보기

기술 문서를 작성하기 위한 첫 발자국부터, 문서의 유지보수와 더 이상 유효하지 않은 문서를 종료하는 단계까지 전체적인 내용을 훑고 있다. 특히 가상의 서비스를 사례로 들어 실제로 문서를 기획하고 구축해나가는 과정을 통해서 내용을 효과적으로 전달하고 있는 것이 이 책의 장점이다.

  1. 독자 이해하기
    • 기술 문서의 사용자를 먼저 파악해봄
      • 사용자 니즈
      • 사용자 패르소나
      • 사용자 여정
  2. 문서화 계획하기
    • 문서의 유형
      • 코드
      • README 문서
      • 시작하기 문서
      • 개념 문서
      • 절차 문서
      • 참조 문서
  3. 문서 초안 만들기
  4. 문서 편집하기
    • 편집 접근법
      • 기술적 정확성 -> 정확한 명명? 혼동을 일으킬만한 용어 은어? 독자가 기대한 결과
      • 완전성 -> Todo, TBD가 채워졌는지? 성공적인 사용을 위한 정보가 다 들어가있는지?
      • 구조 -> 흐름과 분류
      • 명확성/간결성 -> 표현 / 불필요한 부분 / 편향된 언어
    • 편집 프로세스
      • 예) 작성자 검토 -> 동료 검토 -> 기술적 검토
  5. 샘플코드 통합하기
    • 샘플코드의 복잡성을 단계별로 명확하게 나누기
  6. 시각적 콘텐츠 추가하기
    • 스크린샷
    • 다이어그램 (플로우차트, 스윔레인)
    • 비디오 콘텐츠
    • 유지하기
  7. 문서 배포하기
    • 릴리스 프로세스 구축
    • 타임라인 만들기
    • 전달 방식 (매체)
    • 문서가 배포됨을 알리기
  8. 피드백 수집하고 통합하기
    • 피드백 채널
      • 직접 수집
      • 고객지원 업무 중 문제 모니터링
      • 문서의 고객 평가 수집
      • 사용자 설문조사 / 사용자 위원회
    • 후속 조치
  9. 문서 품질 측정하기
    • 기능적 품질 : 이루고자 하는 목표를 달성하는지 (정확한 내용 전달 등등)
    • 구조적 품질 : 얼마나 “잘” 작성되었는지 (명확, 간결 등등)
  10. 문서 구조화 하기
    • 문서는 양이 커짐 … 문서 콘텐츠를 올바르게 구조화 하기
      • 사이트 탐색 구조
      • 랜딩 페이지
      • 탐색 신호 (검색)
  11. 문서 유지 관리 및 지원 중단하기
    • 문서 최신 유지하기
    • 담당자 선정
    • 유지 관리 자동화
    • 문서 삭제

아쉬운 부분

Docs for Developer 에서 약간 아쉬웠던 부분은 번역이었다. 많은 개발 용어들이 영문 표현에 기반을 두고 있는데, 개인적으로는 영어 표기를 어느 정도 그대로 따라가는 것이 추후 내가 책을 통해 얻은 정보와 현업에서 사용되는 용어를 연관시키고 역량을 확장시키는데 도움이 된다고 생각한다. 하지만 번역으로는 쉽게 와닿지 않는 부분이 있어 “원서나 실제 영미권에서는 이 용어를 어떻게 쓰는지” 의문이 들어 중간 중간 추가적으로 찾아봐야 했던 상황이 종종 있었다. (예: 마찰 로그 -> Conflict logging) 출판사 정책 등으로 굳이 개발 용어를 번역 해야한다면, 괄호 또는 주석으로 영문을 함께 표기하는 것이 개발자인 대다수의 독자에게 내용을 전달하는게 더 편리하지 않을까 하는 인상이 들었다.

한빛미디어 <나는 리뷰어다> 활동을 위해서 책을 제공받아 작성된 서평입니다.