Docs for Developers 기술 문서 작성 완벽 가이드,

0. 들어가기에 앞서

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

제목 : Docs for Developers 기술 문서 작성 완벽 가이드 저자 : 자레드 바티 외 4명 번역 : 하성창 출판사 : 한빛 미디어
출간 : 2023년 4월 10일
페이지 : 332

1. TL;DR

• 책의 내용이 적당하며, 발췌독 하기 좋습니다..
• 책의 챕터 단위가 그렇게 크지 않기에 마음 편히 읽을 수 있습니다.
• 본인이 공부한 기술적인 내용에 대한 글쓰기 책이 아닙니다. 카카오 지도 API 문서, 채널톡 API 문서 등 이런 API 문서를 작성해야 하는 사람이라면 읽어 보는걸 추천합니다.
• 그렇지만, 기술적인 글쓰기에 대해 공부해 보고 싶은 분들에게도 좋은 책입니다. 개발자들도 가벼운 마음으로 읽어봐도 좋을 것 같습니다.

2. 이 책을 선택한 이유

이직을 하고 나서 좋았던 점 중 하나는 사내 위키가 활성화 되어 있다는 점 이었습니다. 그러나 위키가 잘 되어 있는 것과 별개로 필요한 정보가 어디에 있는지 찾는건 어려운 일이었습니다. 또한 의미 있는 정보를 기술하는 방식에 있어서 천차 만별이었으며, 저 또한 어떻게 사내 위키에 제가 배운, 추가해야 할 내용을 기술할지 고민이 었습니다. 그렇기 때문에 이 책 기술 문서 작성 완벽 가이드를 읽고 어떻게 문서를 작성 할 것인지 고민해 보기로 했습니다.

3. 리뷰

이 책은 반려동물 소리를 텍스트로 번역해주는 회사를 예시로 들어 책의 내용을 설명합니다. 내부 개발자를 위한 기술 문서가 아닌 외부 상품으로 판매되는 소프트웨어 API 문서를 기준으로 설명을 하고 있습니다.

이 책에서는 단순히 기술 문서를 작성하기 위한 테크닉을 넘어 다양한 것들을 알려주려고 합니다. 문서를 읽는 독자, 독자의 니즈, 독자가 알아야 하는 것 등 독자분석으로 컨텐츠를 시작합니다.

독자 분석이 끝나고 나면 이제 분석한 독자를 기반으로 어떤 컨텐츠를 만들지 컨텐츠에 대해 설명해 줍니다. 그 컨텐츠의 장단점 및 특징을 설명함으로써 독자를 정의 하고 난 이후 어떤 양식의 컨텐츠를 선택할 지 정합니다.

컨텐츠를 정하고 나면, 컨텐츠에 맞는 내용을 기술해야 합니다. 여기서 템플릿이 나옵니다. 잘 작성된 템플릿의 내용과 잘 작성되지 않은 템플릿 내용을 확인할 수 있습니다.

개인적으로 저는 예전에 숱히 읽었던 개발 공식 문서들을 비교해보며, 아 이 개발 문서는 잘 작성되었구나, 아 그 공식문서는 잘 작성되지 않았구나 라는 것을 평가하며 읽을 수 있었습니다.

개인적으로 기술 문서 작성이라고 하길래 기술적인 내용을 작성하는 방식이라고 생각했지만, 외부에 노출시키는 기술 문서를 작성하는 것이라 기대했던 바와는 조금 달랐습니다.

그러나 기술적인 내용 글쓰기에 대해 이론적인 내용과 테크니컬한 방법을 배울 수 있었다는 점이 좋았습니다.

4. 총평

• 카카오 지도 API, 채널톡 API등의 API 문서를 작성해야 하는 사람들에게 적절한 책 입니다.
• 기술 글쓰기에서 우리가 생각하지 못한 이론적인 부분과, 테크니컬한 부분도 설명해 줘서 읽기 편합니다.
• 책의 모든 부분이 필요한게 아니니 발췌독이 필요한 경우에는 발췌독 해서 읽을 것 ! (그러나 1 ~ 4장은 다 읽어 보기를 추천 합니다.)
• 이 책을 읽다 보면 글을 쓰고 싶어질 수 있으니, 공책 같은 것도 미리 준비해 두면 좋습니다.