[리뷰] 개발 과정 전반에 필요한 문서 작성 방법 'Docs for Developers 기술 문서 작성 완벽 가이드'

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

 

개발자로 일하면서 중요하면서도 어려운 것은?

로직 생각할 때? 알 수 없는 에러가 발생했을 때? 해결 방법이 생각나지 않을 떄?

이것 들도 맞지만 문서작성이다.

 

문서는 곧 기록이다.

기록하는 순간에는 이게 굳이 필요할까? 이걸 작성한다고 누군가에게 도움이 되는가? 하는 온갖 생각과 귀찮음이 몰려올 때가 있다.

하지만, 기록의 힘은 빛을 발하는 때가 있다. 그 때가 지금 작성하는 순간이 아닐 뿐이다.

 

최근에 문서의 중요성을 절실히 깨닫는 중이다.

누군가 만든 문서를 보면서 작업을 하는데 대충 만들어둔 문서이다보니 생략된 내용이 많았다.

그러다보니 수시로 작성자에게 물어보게 되는데 그 때마다 돌아오는 답변이 '오래전에 하다보니 기억이 잘 안 난다.'

그래도 관련 자료를 어디서 봤던 건지 찾아서 알려주신다.

 

잘못 작성된 문서는 자료가 없느니만 못한 결과를 초래한다.

 

개발자가 올바른 문서작성을 할 수 있도록 가이드를 제시한 책이 'Docs for Developers 기술 문서 작성 완벽 가이드' 이다.

Docs for Developers 기술 문서 작성 완벽 가이드

이 책을 제목만 봤을 때는 그냥 양식 관련해서 알려주는건가 싶었다.

하지만 내용을 읽어보니 프로젝트 전반에 걸쳐 작성해야 할 문서들에 대한 내용이었다.

각 문서마다 작성을 위해 어떤 고민을 해야할지, 어떤 내용을 담아야 하는지, 어떤 방법으로 작성해야 하는지 등 놓치기 쉬운 부분부터 정말 중요한 부분까지 찝어주는 내용이었다. 즉, 제목 그대로 완벽 가이드였다.

 

책 일부 내용 캡처_README 템플릿 예시

책 일부 내용 캡처_버그 리포트 템플릿 예시

 

책 일부 내용 캡처_챕터10_요약

 

나는 README 작성을 하지 않았다.

사내 문서가 따로 있기도 하고, 깃 커밋 메세지만 잘 작성 하면 되는 줄 알았다.

이런 잘못된 생각을 바로 잡아준다. 

버그 리포트의 경우 회사에서 사용하고 있는 툴이 있다.

책에서 나온 예시와 비슷하게 작성되다보니 읽으면서 비교하고, 보완하면 좋을 점들 찾는 재미가 있다.

 

 

최근 개발자 취업과 관련하여 들은 이야기가 몇 회사에서는 자소서 보다 문서를 중요시 한다는 것이다.

포폴과 관련하여 README, 명세서 등을 주로 본다는 것이다.

개발자에게 개발 능력 만큼 문서 작성 능력도 요구한다는 것을 느꼈다.

 

문서 작성을 아무리 못하더라도 이 책을 참고한다면 많은 도움이 될 것이다.

대충 읽어도 이해할 수 있을 정도로 쉽게 서술하고 있고 예시도 있어서 따라하기 편하다.

급할 땐 매 챕터의 요약만 읽거나, 개발과정 전반에 걸쳐 작성되는 문서에 대해 다루고 있기 때문에 현재 진행중인 과정에 해당하는 챕터만 봐도 된다.

 

나처럼 문서 작성에 안일한 생각을 갖고 있거나 어려움을 겪고 있다면 이 책을 필히 읽어보길 바란다.