Docs for Developers 기술 문서 작성 완벽 가이드
단단한 문서화를 위하여
이번 글은 <Docs for Developers 기술 문서 작성 완벽 가이드> 라는 책의 리뷰로, 한빛미디어의 <나는 리뷰어다> 활동을 위해 책을 제공받아 작성된 서평입니다.
문서화
개발자들에게 문서화는 정기적인 운동처럼, 중요하고 필요하지만 없어도 당장은 티가 안나는, 중요하지만 결국 문제가 터지고 나서야 중요성을 알게 되는 그런 오묘한 것이라고 생각합니다.
소프트웨어 개발을 배우는 과정에서 문서화를 자세히 언급하는 곳은 많지 않습니다. 그렇기 때문에, 많은 개발자에게 “기술문서 작성”을 포함한 글쓰기 와 문서화는 익숙하지 않습니다.
뿐만 아니라, 업무를 하는 과정에서도 당장 쌓여있는 task를 처리하는 것이 이미 만들어진, 그리고 언제 다시 바뀔지 모르는 것을 문서화하는 것보다 훨씬 효과적이라고 생각하기 때문에 문서화에 소홀해지기 마련입니다.
시간이 지나면서, 문서화로 인한 장점이 훨씬 더 많다는 것과 이에 대한 체계적인 접근의 필요성을 국내의 기업들도 느끼기 시작했는데요. 이를 전문적으로 하는 Technical Writter, Developer Relation 등의 직군들이 등장하기 시작했습니다.
그럼에도 불구하고 개발자 혹은 개발조직과 연관되어 업무를 하는 사람들은 위의 전문가 그룹 만큼은 아니지만, 기술 문서를 작성하는 방법을 알고 있으면 좋은 것이 많은데요. 오랜만의 완벽 가이드 라는 글자를 제목에 활용한, 그리고 그만한 가치가 있는 멋진 도서가 등장했습니다.
책의 구성과 목차
이 책에서는 기술 문서를 만들기 이전, Cog.ly라는 가상의 api 서비스를 제안하고 이 서비스를 개발 / 사용하는 이해관계자들의 상황을 설명하는 것으로 기술 문서의 필요성을 이야기하는 것으로 시작합니다.
- 이후 (다른 프로덕트들처럼) 문서화를 먼저 계획하고 초안을 만들고, 피드백 하는 과정에서 챙겨야 할 체크리스트들을 자세히 설명하고
- 실행코드나, 이미지 같은 시각화 마지막으로 문서를 어떻게 유지, 배포할 것인지 에 대한 내용을 설명합니다.
- 원서의 저자는 구글, 리눅스 제단, 스트라이프, MS 등의 기업에서 문서화 관련 업무를 하던 분들이었던만큼 많고 자세한 내용을 담고 있으며
- 추가로, 국내 기업의 Technical Writter 들과도 인터뷰를 통해 어떤 역량이 필요한지, 혹은 이 직업으로 어떤 과정들을 거쳤는지 등을 다루고 있습니다.
마지막으로 기술 문서 작성에 관심을 갖는 사람들을 위해 미처 이 도서에 담지 못한 내용들을 레퍼런스로 달아두었기에 학습이나 실습이나 큰 도움이 되리라 생각합니다.
책의 주요 특징
책의 내용은 특정 프로그래밍 언어나 프레임워크가 아닌 가상의 서비스를 전제로 다뤄지고 있습니다.
그래서 이에 대한 제한이 없는 대신, 서비스가 IT 프로덕트가 아니라면 소개하는 원칙들을 서비스에 적용하기 위해 조금 시간이 필요할 수 있습니다.
물론 책의 제목 자체가 “기술문서” 를 가정하고 만들었기 때문에 큰 문제는 아닙니다.
한편 “글쓰기 자체”를 다루기보단, 기술 문서는 어떤 것들로 구성하는 것이 왜 좋은지와 같은, 조금 더 큰 관점에서 설명들이 이루어집니다. (가령 아래의 예시에서 글의 문체나, UI / UX 적인 관점에서의 페이지 색상 등은 내용에 비해 상대적으로 중요하지 않습니다)
책은 332페이지로 내용이 꽤 많은 만큼 한번에 다 읽기는 어렵지만, 책에서 장을 넘어갈 때마다 주요 내용들을 “요약” 을 통해 정리 해주기 때문에 처음 읽을 때나, 이후에 실제로 문서를 만들며 읽을 때나 활용할 수 있는 여지가 많이 있습니다.
그래서
- 이 책은 개발자에게 장기적으로 도움이 됩니다.
- 개발 문서를 만들어야 하는 비개발직군에게도 꽤 도움이 됩니다.
- 당연히, Technical Writing 관련 직군으로 커리어를 진행 / 준비하는 하는 사람에게는 즉시 도움이 됩니다.
샘플 코드, 명령어, API 호출을 포함하여 문서에서 제공한 예제들을 테스트하면 정확성 문제를 사전에 해결 하는데 도움이 됩니다.
이 문장에 등장하는 단어들을 바로 이해할 수 있다면 이 책을 이해하는 것은 어렵지 않습니다. 그러나 그렇지 않다면 책의 내용을 이해하기 위해 꽤 많은 시간을 투자해야 합니다.
전자책
이번 책은 처음으로 전자책 형태의 도서를 신청 / 제공받아 리뷰를 했는데, 이에 대해서도 리뷰해보려고 합니다.
저는 집에 책이 꽤 있지만, 전자책은 별로 선호하지 않았습니다. 이런 생각들을 했기 때문인데요.
- 전자책) 전용리더가 있어야 읽을 수 있다.
- 일반책) 책을 읽는 “손 맛”이 있다.
- 일반책) 필요할 때 읽을 수 있다. (오프라인)
- 일반책) 내용을 서점에서 미리 확인해볼 수 있다.
- 일반책) 여차하면 저자의 싸인을 받거나, 다른 사람에게 도서를 선물할 수 있다.
새로운 시도를 해보기 위해 전자책을 통해 책은 읽어봤는데 장점은 이러합니다. (단, 구글북스 기준)
- 책의 글자 크기나 폰트 등을 조절하는 커스텀을 통해 읽을 수 있다.
- 주요 키워드가, ex) C4 model 이 어느 페이지에 있는지 검색 가능 (장점)
- 밑줄, 메모, 북마크가 자유롭게 가능 (장점)
- IT 기술서의 경우 링크를 바로 클릭으로 활용 가능 (장점)
- 책을 방향키 하나, 손가락 하나로만 읽을 수 있음 (장점)
- 대체로 전자책은 일반책에 비해 가격이 조금 더 낮음 (장점)
- 크롬을 통해 pc로도 읽을 수 있다. (다운로드는 .acsm으로 가능하지만, 이는 pc가 아닌 패드나 폰에서만 활용가능)
- 물리적 공간을 차지 하지 않음 (장점이자 단점)
- 다른 사람에게 선물하거나, 공유하는 것은 불가능 (단점)
이를 통해 낸 결론은 다음과 같습니다.
내가 여러 번 읽는 것이 목적인 책이라면 전자책도 좋은 선택.
개인적으로는 앞으로 전자책을 지금 보다 더 많이 애용할 것 같습니다.
