[책 리뷰] Docs for Developers 기술 문서 작성 완벽 가이드

해당 서비스에 대한 문서나 관련자료 혹은 히스토리가 있나요?

새로운 서비스를 유지보수하게 되거나, 이직 혹은 신규입사 했을 때 팀원에게 꼭 물어보게 된다. 또한 외부 서비스, 타팀의 서비스를 사용하기 위해 해당 서비스의 문서화된 데이터를 요구하는 경우도 있다.

문서화는 소프트웨어 품질에도 큰 비율을 차지한다.

내가 코드로만 해당 서비스를 파악하며 이해하기보다, 정리된 문서가 있다면 해당 서비스를 이해하기 위한 시간을 줄일 수 있고 이해도도 높아진다. 또한 분석을 위해 삽질 고생할 확률도 낮아지게 된다.

그렇다고 이 문서들이 모두 도움이되느냐? 그건 또 아니다.

아무리 문서 작업이 되어있다고 하더라도 잘못된 방향, 정확하지 않은 정보로 작성되어 있다거나 부산스럽게 작성되어 있다면 전혀 도움이 되지 않는다.

대부분의 개발자들은 ‘아.. 제가 글을 깔끔하게 작성하지 못해서.. 문서화가 어렵네요..’ 식으로 작성을 하지 않는 경향이 있는데 내가 어떻게 문서를 작성해야 할 지 헤메고 있는 개발자에게 이 책은 큰 도움이 될 것이다.

이 책은 문서화를 다루고 있는 책 답게 문서화의 작성 단계처럼 내용이 순차적으로 진행된다. 단순히 문서 템플릿만을 가이드 해주는 것이 아니라 문서화를 하기 위한 마음가짐(!!) 부터 때려박으며 시작한다.

문서화를 진행하기 위한 순서는 크게 다음과 같다.

1. 독자 이해하기
2. 문서화 계획하기
3. 문서 초안 만들기
4. 문서 편집하기
5. 샘플코드 통합하기
6. 시각적 콘텐츠 추가하기
7. 문서 배포하기
8. 피드백 수집하고 통합하기
9. 문서 품질 측정하기
10. 문서 구조화하기
11. 문서 유지 관리 및 지원 중단하기

사실 책을 읽으면서 재미있었던 점은 각 챕터의 초입마다 살럿이라는 주인공을 통해 특정 IT 서비스의 문서화 작업을 맡게되어 진행되는 이야기였다. 문서화 작업을 진행하는 과정에 따라 이야기가 이어지는데 챕터의 존재 이유를 핵심적으로 설명해준달까..?

개인적으로 문서화의 중요성에 대해 설명하는 책들은 많을 지 몰라도 해당 문서를 어떻게 작성해야하는 지에 대해 이렇게 세세히 알려주는 책은 없는 것 같다. 마지막에 필드에서 테크니컬 라이터로 활동하는 분들의 인터뷰가 수록되어 있는데 해당 챕터에서도 많은 인사이트를 얻을 수 있었다.

별점 : ⭐️⭐️⭐️⭐️

한줄평 : 공대 느낌 팍팍 나는 개발자에게 문서화의 A to Z를 알려주는 책.

이런분께 추천 :

1. 개발 문서 작성이 어렵다고 느껴서 문서화에 어려움을 느끼시는 분.
2. 문서화에 관심이 있고 더 좋은 문서를 작성하기 원하시는 분.

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