구글 엔지니어는 이렇게 일한다 #10장 문서자료를 읽고

#10 문서자료

| 일부 내용
대부분의 엔지니어가 코드를 작성하고, 이용하고, 유지보수하며 토로하는 대표적인 불만이 양질의 문서자료가 부족하다는 점 입니다.

 

지금까지의 경험에 한해서는 어디를 가서도 문서자료의 부족함이 없다는 이야기는 못들어 봤다. 

항상 문서 자료가 부족하다는 이야기 뿐이었다. 

 

---

 

| 일부 내용
구글에서 문서자료를 개선하고자 해본 시도 중 가장 성공적이었던 방법은 문서자료를 코드처럼 취급하여 엔지니어링 워크플로에 통합하는 것이었습니다. 그 결과 엔지니어들이 간단한 문서자료를 작성하고 유지보수하는 일이 한결 수월해졌습니다.

 

swagger, jsdoc, postman, redoc 등 이를 활용할 수 있는 도구들이 많이 다양해졌다.

대다수의 사람들이 최소한 API 명세에 한해서는 문서화의 중요성을 인지하고 있다.

 

---

 

| 일부 내용
하지만, 테스트에 대한 투자와 마찬가지로 문서자료에 들인 노력도 날이 갈수록 가치가 커집니다. 문서자료는 단 한번만 작성하면 되지만 결국 수백 번, 수천 번 읽히게 됩니다. 초기 비용은 미래의 모든 독자에게 혜택으로 돌아 갑니다.

 

길을 가다보면 신문을 찍어 내는 곳이 있다. 명확한 회사명은 기억이 나지 않지만 동아일보였던것으로 기억한다.

거기에는 이런 문구가 적혀 있다. "오늘의 기록이 내일의 역사가 된다."

 

테스트 / 문서자료 또한 번거로울지라도 내일을 위해, 후에 이를 통해 이득을 볼 사람들을 위해 작성해야 한다.

 

---

 

| 일부 내용
문서자료가 기존 코드를 유지보수하기 더 쉽게 해준다고 생각하기보다는 유지보수할 대상이 하나 더 늘어난다고 생각합니다.

 

처음에는 나도 이런 생각을 안가졌던것은 아니다. 실제로 현업을 진행하며, 신입때는 작업을 우선적으로 수행하는 경우가 많았다. 

하지만, 어느 정도 시간이 지나고 작업한 내역을 건드려야하는 상황이 왔을때, 내가 작업한 부분임에도 일부만 기억이 나는 경험을 했었다.

당혹스러우면서도 느낀 한가지는 작업 전/후 문서 자료를 만들어 놓아야 겠다는 생각이었다.

 

이런 습관이 들고 난뒤에, 시간이 지나 비슷한 상황을 경험했을때 과거의 내가 작성한 문서 자료는 작업의 컨텍스트나 흐름을 파악하는데 도움이 되었다.