[Book review] 문서자료 - Software Engineering at Google, 구글 엔지니어는 이렇게 일한다.

서문

앞 글인 지식공유 글에서 이어집니다. 

지식을 공유하는 효율적인 방법 중 하나가 문서자료라고 생각한다.

문서자료는 무엇이고 왜 필요할까?

또 많은 사람들이 효율적으로 양질의 문서자료를 관리하려면 어떻게 해야할까?

오늘은 책에서 문서자료 Chapter를 정리하고 사견을 붙여 이야기한다.

 

문서자료

문서자료(documentation)란 엔지니어가 작업을 끝마치기 위해 작성해야하는 모든 부수적인 텍스트이다.

여기에는 별도로 작성한 문서는 물론이고 코드주석까지 포함한다.

 

문서자료가 필요한 이유

개발자로서 내가 생각하는 문서자료가 필요한 가장 큰 이유는 양질의 프로그램을 만들기 위해서라고 생각한다.

좀 더 풀어서 설명하면 팀의 모든 구성원이 더 원활히 역량을 발휘할 수 있게 된다는 것이다.

 

이제 신입딱지를 막 땐 나는 문서자료를 정말 많이 보는데(지금도 많이 보고 있다.) 정말 도움될때가 많다.

반대로 자료가 하나도 없는 코드를 볼때면 능률이 절반이상 깍이는 느낌을 받는다.

모르는 부분은 하나하나 대면으로 질문해야하기 때문이다.

일을 함에 있어서 대면으로 질문하는 것은 문서를 읽는 것보다 에너지를 많이 쓰는 행동이여서 허들이 비교적 높다고 생각한다.

결국 양질의 프로그램을 만드는 시기를 늦추는 작업이라 생각한다.

 

이외에도 시니어 개발자에게도 자신이 당시에 했던 일과 생각들을 적어놓으면 히스토리 파악에도 도움이 될 때가 많다.

기반으로 좀 더 좋은 코드를 만들 수 있고 양질의 프로그램을 만들 수 있게 되는 것이다. 

 

그렇다면 왜 양질의 문서자료는 만들기가 힘들까?

개인적으로 번거롭다고 생각하는 사람들이 많다고 생각한다.

책에 나온것처럼 큰 혜택을 바로 볼 수가 없으니 주저하고 꺼리는 것이다. 귀찮으니까.

이는 시스템적으로 혜택을 주어야한다고 생각한다. 

문서자료 관리

양질의 문서자료가 되려면 관리가 더욱 중요하다.

시간이 지나면서 유효하지 않은 내용이 될 가능성이 높고 결국 방치되어 혼란만 가중시키는 없느니만 못한 자료가 될 수도 있기 때문이다.

구글에서도 같은 문제를 겪었는데 해결법은 코드처럼 관리한다고 한다. 

추적하고 소유자두고 리뷰받는 것까지, 곧 개발 workflow에 통합시키는 것이다. 

정말 좋은 아이디어란 생각이 들었다.

처음엔 정착이 엄청난 시간이 들지도 모르지만 정착되고 나면 이후의 파급력은 상상이상일 것이다.

 

문서자료 리뷰

좋은 문서자료의 특징을 3가지 제시한다.

• 완전성 completeness
  명확성과 trade off 관계이다.
  일어날 수 있는 모든 일을 서술하게 되면 무엇을 설명하는지 명확성이 떨어질 수 있다.
• 명확성 clarity
  목적을 가지고 분명하고 잘 읽히는 글을 말한다.
• 정확성 accuracy
  두루뭉실 하지않고 정확하게 수치나 example이 서술되어 있는 글을 말한다.

결국 좋은 문서란 의도한 하나의 역할을 잘 수행하는 문서라고 생각한다.

독자를 생각하자

또 해당 파트에서 인상적인 부분은 독자를 생각하라는 부분이었다. 구체적으로 TL;DR문을 글 처음에 붙여 글의 목적을 알려주라는 것이다.회사에서도 최근 들어오신 신입분이 이글을 읽으므로써 얻을 수 있는 지식을 글 상단에 요약해놓으신것을 보았는데 인상깊었다.TL;DR이란 Too Long; didn't read의 약자인데 핵심정리 정도로 의역할 수 있다.

 

 

구체적인 가이드를 몇가지 추려 요약해 보았다.이제 문서자료를 작성하는 일만 남았다!