[Book Review] Docs for Developers (기술 문서 작성 완벽 가이드)

 

 

개발자를 위한 문서는 개발자 경험을 향상시키고 제품의 채택률을 높이며 고객 지원 비용을 낮춰준다고 한다. 또한 장기적으로는 제품의 평판을 높이고 경쟁 우위를 제공하여 사업의 성공에 중요한 역할을 한다고 한다. 개발자 문서를 잘 만들고 관리하는 방법은 무엇일까? 이 책에서는 문서화 하기 전 독자 이해하기, 문서화 계획하기, 초안 만들기, 편집 하기, 샘플 코드 통합하기, 시각적 콘텐츠 추가하기, 문서 배포하기, 피드백 수집하고 통합하기, 문서 품질 측정하기, 문서 구조화 하기, 문서 유지 관리 및 지원 중단하기 까지 개발자 문서를 완벽하게 만들기 위한 가이드를 End-to-End로 제공한다. 코드 자체가 잘 작성된다면 그 자체로 문서화가 된다는데, 복잡성과 규모가 일정 수준 이상인 프로젝트에서는 코드 레벨에서 이해를 시작하는게 아니라 다른 사람들이 빨리 이해할 수 있도록 사람이 읽을 수 있는 형태의 문서가 훨씬 더 효과적이다. 

 

먼저 문서화 하기 전에 사용자가 누구인지 이해하는 과정이 필요하다. 예를 들면 개발자, 프로덕트 매니저 또는 시스템 관리자와 같은 역할에 따라 사용자를 정의할 수 있다. 이러한 사용자의 역할에 따라 고려해야할 점도 달라진다. 예를 들면 사용자가 개발자인경우 보유 기술, 사용 프로그래밍 언어, 개발 환경, 사용 운영 체제, 팀 내 역할을 고려하여 카테고리를 만들어야한다. 그 다음에 사용자의 니즈가 무엇인지에 대해서 사용자 조사를 실시하여 독자에 대해 깊이있게 이해하는 과정을 거친다. 

 

그 다음 사용자에게 가장 중요한 유즈케이스를 파악하여 그들의 니즈를 해결하는 콘텐츠 유형으로 문서화 계획을 세운다. 코드 주석만으로는 사용자가 시스템을 이해하기에 충분하지 않기 때문에 README를 작성하는 것이 좋다. README는 Mark Down 형태로 작성하며, 간결하고 유익하며, 정확하게 최신 정보를 담고 있어야 한다. README에 담겨야할 내용 중 가장 중요한건 How-to 가이드다. 여기에 필수 조건을 포함시켜야하며, 참조 문서나 API 관련된 정보를 기입할 수 있다. 그 다음 문서의 제목에는 문서를 읽는 목적을 요약해두어야하며, 목표를 한가지로만 제한하는 것이 좋다. 목표가 여러개라면 여러 개의 문서가 필요하다. 

 

이렇게 개발자 문서를 작성하는데 있어서 제일 중요한 것은 '독자'를 최우선으로 해야한다는 것이다. 작성하는 문서가 독자들에게 최대한 이해하기 쉬운 내용인지에 대한 통찰력을 기르는 것도 중요하다. 이렇게 하면 독자 누구나 이해하기 쉬울 수 있는 문서를 작성할 수 있다고 한다. 

 

책의 마지막 부분에는 실제 업계에서 테크니컬 라이터로 활동하고 계시는 11명인의 인터뷰가 수록되어있다. 그 중 가장 기억에 남는 말은 기술 문서의 작성 목적은 서로 다른 기술 스택을 보유한 개발자 모두가 협업의 본질을 이해하고, 해당 업무가 처음이더라도 원활하게 일할 수 있는 훌륭한 가이드나 매뉴얼을 남기는 것이라고 한다. 

 

한빛미디어에서 출간된 기술 문서 작성 완벽 가이드라는 책은 테크니컬 라이터라는 직업에 대해 관심을 갖고 있거나, 개발자 문서를 더 잘 쓰고 싶은 사람, 개발자 문서를 이제 막 써야되는 사람에게 모두 추천하고 싶은 책이다. 

 

 

 

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