Daniel’s review #1: Docs for Developers: 기술문서 작성 완벽가이드

처음으로 소개드릴 책은 Docs for Developers. 테크니컬 라이터 분들이 극찬을 하는 책입니다.

그 유명한 네임드 도서! Docs for Developers

“기술문서도 실제 프로덕트만큼 중요한 콘텐츠 프로덕트입니다.”

기술 문서도 콘텐츠 프로덕트입니다. 고객이 개발자인 것이 일반적인 서비스와 다른 점입니다. 예로는 Kubernetes와 Kubernetes 공식 문서가 있습니다. 필자는 서드파티 프레임워크나 라이브러리가 동일한 수준의 사용성과 성능을 제공하지만 문서가 제대로 없다면, 이 프레임워크나 라이브러리는 웬만해서는 선택하지 않을 겁니다. 대신 잘 작성된 문서를 제공하는 서드파티를 선택할 겁니다. 왜냐하면 빠르게 개발해야 하는데, 문서가 없기에 정상적인 동작을 살펴보고 확인하는 시간이 더 많이 필요하기 때문입니다. 이 때문에 잘 작성한 기술 문서가 중요합니다.

이 책에는 기술 문서를 문서화 프로세스를 이용해서 기술 문서를 만드는 방법과 유지 보수 방법이 간략하게 잘 담겨져 있습니다. 개발자의 관점에서 소프트웨어 개발 프로세스의 최종 산출물이 코드 대신 문서인 것처럼 보입니다. 필자가 처음 읽었을때 좋은 개발 프로세스 책의 요약본을 본 것 같은 착각이 들었습니다. 어떤지 살펴볼까요? 이 책에서 소개한 기술 문서 작성에는 아래와 같은 단계를 밟게 됩니다.

• 독자 설정 및 인터뷰
• 문서 작성 계획과 로드맵을 세움
• 초안 작성
• 리뷰
• 문서 배포
• 통합 피드백 반영
• 품질 측정

익숙하지 않나요? 순서만 조금 다를 뿐 개발 프로세스와 많이 유사합니다. 크게 보자면 고객에게 콘텐츠(문서)를 서비스할 플랫폼을 만든다는 점에서 사실상 같다고 볼 수 있겠습니다.

책 요약은 링크한 한빛미디어 페이지에 잘 나와 있습니다. 여기를 참고하시면 도움이 많이 될 겁니다.

추천 대상

기술 문서 쓰는 방법을 전문적으로 배우지 않은 분(개발자 포함)에게 권하고 싶습니다. 완전 디테일 하게 어떤 문장이 좋다는 것은 없지만, 기술 문서가 지향해야 하는 바를 제시합니다. 그렇기에 입문서라고 보면 되겠습니다. 각 잡고 쓰는 기술문서는 어떻게 탄생하게 되는지 그 과정을 잘 보여줍니다.

본인이 개발자라면 읽어보라고 권하고 싶습니다. 최소한 1장은 꼭 읽으라고 권하고 싶습니다. 의외로 많은 개발자가 독자가 나 만큼 알 것이라고 가정하고 글을 씁니다. 그래서 회사 내부의 문서를 보다 보면 직접 물어보지 않거나 코드를 열어 보지 않으면 모르는 내용이 꼭 생깁니다. 이 책은 독자가 나 만큼 알 것이라는 가정을 버리도록 방향을 제시하고 있습니다.

장점

이 책의 큰 장점은 꽤나 짧고(330쪽 내외) 핵심을 잘 담고 있습니다. 그리고 현업 테크니컬 라이터와의 인터뷰를 통해서 이분들이 얼마나 고생하는지와 어떻게 가치를 두고 기술문서 작성하는지 알 수 있습니다.

단점

짧은 만큼 간략합니다. 그래서 구체적인 예시가 부족하다고 생각할 수 있습니다. 참고자료(부록 C)를 찾아보면 보완이됩니다. 다만, 번역서이기 때문에 모든 기준이 영어라는게 조금 아쉽습니다.

 

인상 깊은 구절을 몇 개만 발췌해 봤습니다.

사람들이 다른 사람도 자신과 같은 지식을 갖고 있다고 가정한다. 그들은 이러한 인지적 편향을 지식의 저주(Curse of knowledge)라고 명명했습니다. (p. 30)

개발자들 사이에 이런 인지편향은 생각 외로 많이 퍼져 있습니다. 문서도 대체로 자신과 비슷한 지식을 알고 있는 대상으로 쓰인 경우도 많이 보았습니다. (필자도 이런 문서를 많이 썼습니다. 😅)

사용자의 이해를 검증할 때는 사용자의 니즈(needs)에 중점을 두며 이는 사용자의 욕구(wants)와는 다릅니다. (p.36)

많은 경우 사람들은 욕망을 이야기하기 때문에 그 사람에게 정말로 필요한 니즈(needs)가 가려지는 경우가 많이 있습니다. 예를 들면, 주니어 개발자인 김 씨는 개발을 실력을 높이기 위해 맥북 프로(wants)가 필요하다고 생각하지만 클린 코드 강의(needs)가 본래의 목표를 달성시킬 수 있는 수단입니다. 이 책에서는 이 needs(니즈)와 wants(욕망)를 구분해서 보는 방법을 예시(여행 가는 수단으로의 스포츠카(wants)와 버스표(needs))를 들어 간결하고 명확하게 설명하고 있습니다.

좋은 피드백을 제공하려면 다음을 명심해야 합니다.

- 사람이 아니라 아이디어에 집중하기

- 건설적인 제안 덧붙이기

- 피드백을 받는 사람이 피드백에 반응할 시간 주기

(p.116)

당연한 얘기지만 놓치고 있는 것이 아닐까요?

우리가 무엇을 발견하든 우리는 모든 사람이 당시에 알고 있던 것 그들의 기술과 능력, 사용가능한 자원, 당면한 상황에서 최선을 다했다는 점을 이해하고 진정으로 믿습니다. (in The Prime Directive, Norm Kerth, Project Retrospectives: A Handbook for Team Review) (p.117)

위 인용은 회고 관련 책에서 나오는 내용입니다. 이런 믿음이 없다면 선순환을 일으키는 건강한 리뷰 및 회고 문화가 정착하기 어려울 겁니다.

마지막 한마디

이 책을 볼 때는 책의 명성에 비해서 뻔한 내용이라 별로다라는 평가가 꽤 있었습니다. 필자의 경우엔 “뻔하기 때문에 중요한 내용이다”라고 생각이 하기도 했고, 다른 직업군을 들여보는 재미도 있어서 꽤나 즐겁게 읽었습니다.