개발자들이 문서화를 하는 이유는 뭘까? 왜 하는거지?

 

 

 개발 조직에는 많은 개발 문서가 있다.

 그리고 그 중 90%는 폐기 대상이다.

                              - 트레바리 CTO

 

 

  누군가 트레바리 CTO에게 이런 질문을 했습니다. "쿠팡에 계실 때 개발조직은 문서화를 어떻게 하셨나요?"

문서화...

 

오늘은 이 문서화에 대해서 이야기해보려 합니다.

 

 이전 근무하던 회사에서도 트레바리와 같은 atlassian의 Confluence를 사용했다. 그 때 사용되었던 형태를 살펴보면 다음과 같은 상황에 사용되었던 것 같아요.

 

- 개발 가이드

- 메인 서비스의 아키텍쳐

- 백엔드 개발자가 프론트엔드 개발자에게 공유할 API

- 특정 도구에 대한 사용법

- v1, v2.., deprecated 릴리즈 가이드

- 프로젝트의 계획 및 회고

...

 

 이전 직장의 서비스는 약 10년동안 숨셨던 서비스였던 만큼 그 만큼 많은 문서화가 있었으며 가장 처음으로 마주했던 문서는 어떻게 개발을 할 수 있는지에 대한 개발 가이드 였던것 같습니다. 프로젝트 처음 세팅 방법과 Backbone.js, JPA 설명, spring mvc 등등... 대부분의 내용은 만약 기능을 추가하고 싶다면 어떻게 해야되는가? 가 이였던것 같아요.

  여기서 흥미로웠던 부분은 그 당시 문서는 프로젝트 세팅의 기준은 STS 라는 IDE 이였고, 저의 도구는 intellij습니다. (사진이 있었으면 참 좋았을텐데... 아쉽네요.) 그리고 제가 퇴사하는 그날 까지 그 문서는 STS 기준의 프로젝트 세팅 내용으로, 여전히 그곳에 있었습니다.

 

 단정지을수는 없지만 오랜시간 운영된 서비스 회사일수록 이런 일은 많지 않았을까요?

 

이쯤에서 생각해보면 좋을만한 주제는 아래와 같습니다.

 

우리는 왜 변경해야 된다는 사실을 못했을까?

문제점을 이 무엇일까?

좋은 문서화는 어떤 문서화일까?

문서화를 왜 할까?

 

트레바리는 문서화에 대해서 명확한 기준을 가지고 있습니다.

 

문서에 Howto 가 담기는 순간 그건 관리해야만 하는 문서로 간주합니다.

 관리를 해야만 하는 문서란 계속 관심을 가져야하는 문서라는 의미이고, 이는 Howto를 이해할 수 있는 사람만이 볼 수 있습니다. 이는 문제를 발생시킵니다. 만약 1년 뒤에 그 문서를 본다면, 의미가 있을까요? 이미 Howto 가 표현된 문서를 보는게 의미가 있을까요?

 

트레바리 개발문화는 문서화에 대해 문맥을 전달하는 용도라 판단합니다.

문맥을 전달하는 용도란?

 특정 그룹(ex, 테크유닛)만 이해할 수 있는 글이 아닌, 누구에게나 이 문서를 보면 어떤 맥락인지 이해할 수 있어야 합니다. 

조금 더 구체적으로, 결제 시스템을 개선해야 한다고 가정해봅니다. 그렇다면 어떻게(Howto) 개선해야될 것인가를 문서화 하는 것이 아니라, 왜(Why) 결제 시스템을 개선하려고 하는지- 그래서 최종적으로 무엇(What)을 전달할 수 있는지 문서화되어야 합니다.

 

 문서화는 관리될 수 있는 부분이 아니라고 생각합니다. 관리가 되어져야 한다면, 그만큼의 각오가 필요한게 아닐까요?

조금 더 나아가 생각해본다면 효과적인 문서화는 텍스트보다는 그림으로 표현되어 읽는 독자로 하여금, 시각적인 이해도를 높일 수 있다면 그게 더 좋은게 아닐까요?

 

문서화도 결국에는 사람이 관리하기 때문에, 우리는 시간이 지남에 따라 관리할 수 없게 되는게 문서화일 테니까요.