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

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

문서화는 굉장히 중요하다고 생각한다. 신입 개발자가 입사했을 때, 모든 정보를 습득할 수 있게 하며 개발 과정을 엿볼 수 있게한다. 대표적으로 마이크로소프트 문서를 보자. 비쥬얼 스튜디오에서 발생한 모든 오류에 대한 정보가 이미 문서화되어있다. 심지어 개발을 위한 기초 가이드 문서도 잘 작성되어있다. 물론 이 문서화하는 과정은 굉장히 번거롭고 귀찮은 작업이다. 가끔보면 이 문서화를 왜 해야되나 라는 생각이 들 정도이다. 그러나 개발자라고 칭한다면 문서화는 해야한다.

 

부제로는 테크니컬 라이터들을 위한 기술 문서 작성 가이드북이지만 대부분의 개발자들한테도 통용되는 얘기라고 생각한다. 개발자들은 단순히 알고리즘을 구현하고 코드만 작성하는 것이 아니다. 기획에도 참여하여 어떠한 부분이 가능하고 안되는지 토론하고, 개발 과정을 문서화하며 작성한 코드가 어떻게 동작하는지 주석과 UML과 같은 순서도도 작성해야한다.

 

이 책은 '강아지 음성 번역 서비스'라는 가상의 Corg.ly 서비를 만드는 개발 팀의 스토리를 따라가며 개발 문서가 어떤 단계를 거쳐 작성되는가를 살펴본다. 테크니컬 라이팅은 기술 정보를 가공하여 독자가 소화하기에 적합한 문서로 만드는 일이다.물론 이 작업은 제품의 성격에 따라 천차만별로 달라진다. 그렇기 때문에 책에서는 가상의 서비스를 예시를 들었지만 포괄적인 개념에서 설명해주고 있다.

 

어찌되었든 기술 문서의 핵심은 간결하고 명확해야 한다는 것이다. 개발자가 아니여도 해당 제품이 어떠한 방식으로 동작하는지 이 문서가 무엇을 설명하고 있는지 알 수 있어야 한다는 것이다. 그렇다면 간결하고 명확한 문서화를 위한 단계는 어떤식인가는 아래와 같이 서술한다.

개인적으로 핵심이라 생각하는 챕터는 6과 8,9 이다. 시각적 콘텐츠는 굉장히 중요하다. 아무리 글을 굉장히 잘 썼다고 하더라도 전체 구조를 한번에 보여주는 시각적 자료만 못하다. 시각적 콘텐츠를 만드는 도구는 많지만 사람들이 간과하는 부분이 있다. 바로 회의때 종이 위에 끄적였던 자료만으로도 충분히 훌륭한 시각적 자료가 된다는 것이다.

 

이 책에서 살짝 아쉬운 점이라면 포괄적인 설명을 하기 위해 확실한 예시가 부족하다는 느낌을 받았다. 가상의 서비스를 토대로 스토리텔링 방식으로 서술한건 좋았지만 처음보는 사람에게는 너무 두리뭉실한 느낌이다. 차라리 실제 예를 토대로 각각을 설명해주는 방식은 어땠을까 하는 아쉬움도 있다. 물론 활용하는 방식에 따라 이렇게 포괄적인 방식으로 설명해주는 것이 더욱 좋을 수 있다.

 

여담으로 이번에 e-book으로 처음 신청해보았다. 그러나 이런 기술 서적들은 e-book으로 받기 보다는 실물 책으로 받는 것이 훨씬 읽기도 편한것을 느꼈다. 익숙하지 않아서 보는 것이 불편한 것도 있지만 특정 내용을 보기 위해 빠르게 챕터를 훑는 것이 안되니 답답하였다. 다음부터는 기술 서적은 실물로만 받아야겠다.

 

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