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

기술 문서를 작성하는 법에 대한 내용을 담고 있는 'Docs for Developers 기술문서 작성 완벽가이드'라는 책입니다. 개발자들이 개발을 하면서 매일 같이 접하게 되는 공식문서가 사실 기술문서인데요. 공식문서를 보면 A 공식문서는 이해가 엄청 잘 되고 깔끔하게 쓰여졌다는 느낌이 들기도 하지만, B 공식문서는 뭔가 가독성이 좋지 않고 내가 찾고 싶은 내용을 찾는 게 어렵다고 느껴질 때도 있습니다. 이 책을 읽으면서 왜 쉽게 읽히고, 어렵게 읽히는지에 대한 이유를 알 수 있었던 것 같습니다. 또 잘 읽히는 기술문서를 작성하기 위해서는 어떻게 해야할 지에 대한 방법도 알 수 있었습니다.

 

이 책은 '강아지 음성 번역 서비스'를 만드는 개발 팀에서 이 서비스를 사용할 사용자들을 위해 기술문서를 만든다는 컨셉으로 시작합니다. 만약에 내가 팀원으로서 기술문서를 작성해야 하는 입장이라고 생각하고 읽었더니 더욱 몰입해서 볼 수 있었습니다.

또 책의 저자분들이 테크니컬 라이팅을 하시는 분들이다 보니 이 책의 내용도 엄청 잘 읽히는 것도 있었습니다.

 

책의 목차는 아래와 같은데요. 사실은 기술문서를 작성하는 순서도 아래와 같습니다.

1. 독자 이해하기

2. 문서화 계획하기

3. 문서 초안 만들기

4. 문서 편집하기

5. 샘플 코드 통합하기

6. 시각적 콘텐츠 추가하기

7. 문서 배포하기

8. 피드백 수집하고 통합하기

9. 문서 품질 측정하기

10. 문서 구조화하기

11. 문서 유지 관리 및 지원 중단하기

부록 A, B, C

 

각 챕터마다 설명이 친절하게 잘 되어있고 예시도 많아서 하나씩 따라해보는 재미가 있을 것 같았습니다.

제가 인상 깊었던 내용을 간단하게 정리해보면 좋을 것 같습니다.

 

'문서 작성에서 어려운 일 중 하나는 빈 문서를 대면하는 것입니다. ...(중략) 이 어려움을 인정하는 것이 문제를 풀어나가는 첫 번째 걸음입니다'

- 우리가 글을 쓰는 것을 어려워 하는 이유는 처음부터 글을 완벽하게 써야할 것 같다는 부담을 느끼고 시작을 하는 것 조차 두려움을 느끼기 때문이라고 생각합니다. 이 책에서는 이것은 원래 어려운 일이 맞고, 처음부터 완벽하게 작성할 필요가 없다. 초안을 먼저 작성하고, 쓰고 싶은 순서대로 쓰고 여러번 쓰고 피드백을 반영해가면서 결과물을 만들어내자는 작성 방식을 소개하고 있습니다.

 

'기술 문서에는 대상 독자가 반드시 있어야 하고 독자의 눈높이에 맞게 기술 수준을 풀어서 설명해야 하는 거죠. 독자가 알고 싶어 하는 바를 명확하고 간결하고 일관되게 전달하는 것이 매우 중요합니다.'

- 부록A에 보면 국내 테크니컬 라이터분들의 인터뷰를 확인할 수 있는데요. 모든 분들께서 공통적으로 중요하게 여기는 내용은 독자를 파악하고, 독자의 니즈를 충족시키는 글을 작성해야 한다는 것입니다. 이를 통해 기술 문서를 통해 전달해야 하는 가장 최우선의 가치가 무엇인지 알 수 있었습니다.

 

'픽사에서는 창의적이거나 기술적인 작업에 대한 피드백을 제공할 때 플러싱이라는 규칙을 따라야 하며, 이 규칙은 다음과 같습니다. 건설적인 제안을 덧붙이는 경우에만 아이디어를 비판할 수 있습니다.

- 제가 NEXTSTEP 에서 글쓰기 워크숍 교육을 들었을 때도 경험했던 내용이었는데요. 다른 사람의 의견이 아쉽다고 말을 하려면 어떻게 개선해야할지에 대한 내용도 함께 얘기를 해줘야 한다는 것입니다. 누군가의 의견에 '그건 좀 별로인데요?'가 아니라 '그건 이러한 측면에서 조금 아쉬운 부분이 있는 것 같아요. 혹시 이렇게 해보면 어떨까요? 그러면 아쉬운 부분을 해소할 수 있을 것 같아요!'와 같이 제안을 해줘야 한다는 것이었습니다.

 

이 외에도 마음에 와닿고 기술 문서를 작성하는데 있어 도움이 되는 내용들이 책의 시작부터 끝까지 듬뿍 담겨있는데요.

문서화에 관심이 많고, 문서를 작성해야 하는 상황이라면 이 책을 통해 두려움을 없애고 좋은 문서를 작성하실 수 있다고 생각합니다.

 

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