개발을 하다 보면 무언가 정리하여 문서화 할 필요성을 느낄 때가 있습니다. 편리한 문서화를 위하여 Confluence와 같은 서비스를 사용하는 기업도 점차 많아지고 있습니다. 그러나 잘못 된 문서화는 하지 않는 것보다 못한 일이 되기 쉽습니다. 피플펀드컴퍼니에서 엔지니어로 일하며 고민하고 있는, 문서화에 대한 이야기입니다.

잘못 된 문서화

간단합니다. 구현을 대신하려 하는 것은 잘못 된 문서화입니다. 문서의 내용이 사실을 담고 있는지는 중요하지 않습니다. 문서는 구현을 보완할 뿐, 절대로 대체할 수 없기 때문입니다. 이와 같은 문서화는 무언가 해결한 듯한 착각을 불러 일으켜, 정작 문제 해결을 늦추게 됩니다. 문제 해결에 필요한 시간이 부족하다면, 임시로 문서화를 하되 반드시 구현으로 이어져야 합니다. 엔지니어는 문제를 해결하는 사람이지 주의 사항을 알리는 사람이 아니기 때문입니다. 도로에 구멍이 났을 때 엔지니어의 역할은 그 구멍을 메우고 다시 나지 않게 하는 것이지, “여기 구멍이 있으니 아무도 지나가지 마!” 라고 외치는 것이 아닙니다. 구멍 옆에 울타리를 설치하는 것 역시 아니고, 울타리를 페인트칠하는 것은 더욱 아닙니다.

잘 된 문서화

문서화는 구현으로 표현하기 어려운 정보를 보충하는 것입니다. 예시는 다양합니다. 코드의 내용을 시각화하여 보충하는 것은 잘 된 문서화입니다. 코드는 텍스트로만 이루어져 있어, 때로는 흐름도와 차트 등 시각적 표현이 더욱 효과적이기 때문입니다. 여러 프로젝트에 분산되어 있는 구조를 정리하는 것은 잘 된 문서화입니다. 코드는 프로젝트 단위로 관리되기 때문에 이를 넘어서는 정보를 표현하기 어렵기 때문입니다. 기술적 의사 결정 과정을 정리하는 것은 잘 된 문서화입니다. 시스템 디자인과 기술 스택 등에 대한 의사 결정은 그 결과만 구현에 반영되어, 배경을 알기 어렵기 때문입니다. 이 외에도, 정말로 구현에 담을 수 없는 정보를 표현한다면 잘 된 문서화라고 이야기할 수 있습니다.

마치며

문서화에 앞서, 그 대상을 충분히 고민해야 합니다. 잘못 된 문서화를 하고 있다는 생각이 든다면, 얼마나 시간을 들였든 과감히 삭제하고 제대로 된 구현에 시간을 쓰는 편이 낫습니다.