"애자일(Agile)인데 왜 문서화를 강요하나요?" - 문서화의 진짜 의미를 다시 묻다.

Software Documentation

 
적은 인원으로 운영되는 소프트웨어 개발 조직에서는 개발자들이 매일 전쟁과도 같은 일정 속에서 코드를 작성하고, 버그를 잡고, 기능을 배포하며 하루하루를 보냅니다. 이런 현실 속에서 “이 기능에 대한 문서도 작성해 주세요”라든지 “게이트 점검을 위해 설계서를 제출하세요” 같은 요청이 들어오면, 개발자들은 본능적으로 거부감을 느끼게 됩니다.
 
“우리는 애자일인데, 애자일은 문서화보다는 작동하는 소프트웨어를 중시하는 거 아닌가요?”
“도대체 언제 문서화까지 합니까, 코딩도 벅찹니다.”
“게이트 문서화는 형식적인 절차일 뿐, 실질적인 개발에는 도움되지 않아요.”
 
이러한 반응은 단순히 문서화를 싫어해서라기보다는, 그 문서화가 진짜 ‘가치 있는 활동’인지에 대한 의문 때문일 것입니다.
 
이번 포스팅에서는 이러한 현장의 목소리를 충분히 이해하면서도, 그럼에도 불구하고 문서화가 왜 필요한지, 그리고 어떻게 하면 소수의 개발조직에서도 부담 없이 문서화를 잘할 수 있는지에 대한 고민을 다뤄보고자 합니다.
 
참고: 다음 글은 이전에 문서화에 대해 작성한 포스팅입니다.
 

소프트웨어 공학: 소프트웨어 문서화의 중요성과 적절한 작성 시점

 

애자일 선언이 진짜 말하고 싶었던 것

우선, 애자일(Agile) 선언에서 문서화가 필요 없다고 언급하지 않습니다. 다음에서 보는 바와 같이 오히려 애자일 선언은 문서화보다 더 중요한 것이 있다고 말합니다. 

"Working Software over comprehensive Documentation"

 
“Comprehensive documentation보다 Working software를 더 가치 있게 여긴다
즉, 완전한 문서보다 작동하는 소프트웨어를 더 중요시한다.”

 
그런데, 이 말은 문서화를 하지 말자는 뜻이 아니라, 문서를 위한 문서를 만들지 말자는 것입니다. 문서가 ‘전달수단’이자 ‘협업도구’로 기능하지 않고, 단지 검토 회의용으로 형식적으로 존재한다면 그건 단순한 시간 낭비일 뿐입니다.
 
즉, 애자일은 문서화를 부정한 것이 아니라, 실질적인 협업과 작동하는 결과물을 중심에 두자는 것입니다. 다만 완전하고 복잡한 문서를 작성하는 데 모든 리소스를 쏟아붓지 말라는 경고를 담고 있습니다.
 
 

적은 인원이기 때문에, 오히려 문서화가 필요하다

소수의 개발팀에서는 “우리끼리는 다 알고 있다”는 전제가 깔리기 쉽습니다. 하지만, 다음과 같은 상황을 한번 상상해 보시기 바랍니다.

- 어느 날 갑자기 한 명의 핵심 개발자가 장기 휴직에 들어갔다.
- 새로운 팀원이 투입되었지만, 이전 구조를 이해하는 데만 수 주가 걸렸다.
- 과거에 논의한 설계 결정이 기억나지 않아 같은 실수를 반복했다.
- 테스트 시점에서 기능 요구사항의 변형이 드러났지만 기록이 없어 고객과 실랑이가 벌어졌다.

 
이런 문제들은 모두 문서화의 부재로 발생하는 비용입니다. 적은 인원으로 빠르게 움직여야 할수록, 바로 그런 이유 때문에 조금이라도 기록을 남겨야 개발 생산성과 일관성이 유지됩니다. 애자일에서는 이것을 ‘지속 가능한 개발(sustainable development)’이라 부릅니다.
 
즉, 적은 인원이기 때문에 문서화가 비효율적인 것이 아니라, 적은 인원이기 때문에 더더욱 최소한의 문서화라도 필요합니다. 협업의 연결고리를 만들어주는 ‘살아있는 문서’가 있어야만 팀 전체가 같은 방향을 보고 나아갈 수 있습니다.
 

실무에서 흔히 겪는 문서화에 대한 불만들

실무에서 개발자들이 문서화를 부담스러워하는 이유는 단순하지 않습니다. 대표적으로 다음과 같은 이유가 자주 언급됩니다.

1. 형식적인 문서화만 요구된다.
2. 게이트 리뷰를 위해 ‘형식’에 맞춘 설계서, 회의록, 보고서 등을 반복 작성하게 됩니다. 이런 문서는 대부분 실제 개발에는 거의 활용되지 않고, 한번 리뷰 후에는 버려집니다.
3. 문서화가 개발과 분리되어 있다
4. 개발은 코드에서, 문서화는 문서관리 시스템에서 따로 진행되다 보니, 둘 사이의 싱크가 어긋납니다. 코드가 바뀌었지만 문서는 그대로이고, 누가 무엇을 고쳤는지도 알 수 없습니다.
5. 문서화를 요구하면서 애자일을 말한다
6. “우리는 애자일합니다”라고 말하면서도, 고전적인 폭포수 모델의 문서 게이트를 그대로 강요하는 이중적인 구조가 존재합니다. 애자일도, 전통적 방법론도 아닌 혼합된 혼란이 문서화에 대한 반감을 더욱 키웁니다.

이 모든 문제는 결국 하나로 귀결됩니다.
“문서화가 도움이 되지 않는다”는 인식입니다.
 

문서화는 ‘양’이 아니라 ‘시점과 맥락’이 중요하다

애자일에서 강조하는 문서화는 작성 시점과 내용의 일치성, 그리고 협업을 위한 최소한의 정보 공유입니다. 다음과 같은 방식으로 접근하면 문서화는 더 이상 짐이 되지 않고, 오히려 개발을 돕는 수단이 됩니다.
 

 1. 개발 중 바로바로 기록하라

개발이 완료된 후 뒤늦게 문서를 쓰려고 하면 기억도 나지 않고, 작성에 대한 의지도 떨어집니다. 기능 설계, API 작성, 오류 수정, 기술적 의사결정 등의 맥락은 그때그때 간단히 적는 것이 가장 효과적입니다.

• API 변경 시 Swagger 문서 자동 생성
• ADR(Architecture Decision Record)을 한 문장이라도 남김
• Wiki에 이슈 단위로 회의 요약 메모 작성

2. 문서를 코드 옆에 두라

문서를 별도로 관리하면 업데이트가 힘듭니다. 코드와 함께 저장되는 README, 주석, 자동화된 문서는 코드 변경과 함께 쉽게 유지보수할 수 있습니다.

• Git에 문서 커밋 포함
• 코드 내부에 docstring, JSDoc, XML Doc 등으로 문서화
• Wiki 페이지 대신 코드베이스 내 /docs/ 폴더 구성

3. 문서도 팀 문화로 만들자

문서화는 누군가 한 명이 하는 일이 아니라, 팀 전체가 공유해야 할 문화입니다. “이 기능을 처음 보는 사람이 이해할 수 있을까?”라는 질문을 스스로에게 던지는 문화를 조성해야 합니다.

• 코드 리뷰 시 문서 여부도 함께 체크
• 회고에서 “최근 문서가 얼마나 도움이 되었는가?“를 점검
• 신규 인원 온보딩 시 문서의 품질을 기준으로 피드백 받기

 
 

문서화는 코드 품질을 높이는 ‘기술적 투자’입니다

문서화에 시간과 노력을 들이는 것이 비효율이라는 인식은 매우 단기적인 관점입니다. 실제로, 다음과 같은 점에서 문서화는 코드 품질을 올리는 도구가 됩니다.

• 테스트 케이스 설계의 근거가 되는 시나리오 문서
• 반복된 설계 이슈를 방지하는 의사결정 기록
• 버그 수정의 단서가 되는 코드 변경 이력
• 온보딩 속도를 줄이는 시스템 구조 문서

이러한 문서들은 단순히 보기 좋으라고 작성되는 것이 아니라, 개발자의 사고를 정리하고, 더 나은 설계를 가능하게 하며, 오류 가능성을 줄이는 기술 자산입니다.
 

---

마치며... ‘살아있는 문서화’를 실천하는 것이 진짜 애자일이다

정리하자면, 애자일 선언에서 말하는 “Working software over comprehensive documentation”은 문서화 무용론이 아니라, 문서의 실용성과 가치를 되돌아보자는 제안입니다.
 
작은 조직일수록, 빠르게 움직일수록, 팀의 맥락을 공유하는 ‘살아있는 문서화’는 더더욱 필수적입니다. 단순히 문서를 줄이자는 것이 아니라, 불필요한 문서는 과감히 버리고, 꼭 필요한 문서는 바로 지금, 코드와 함께 작성하자는 것이 애자일의 진짜 정신입니다.
 
“언제 문서화를 하느냐”고 묻는다면, 이렇게 대답해야 합니다.
 
“코드를 작성하는 그 순간이 바로 문서를 쓰는 순간입니다.”
 
지금 바로 실천 가능한 ‘작은 문서화’부터 시작하는 문화가 조속히 만들어지길 바래봅니다. 그래서 문서화가 곧 코드 품질의 출발점이며, 개발자의 생각을 팀의 자산으로 만드는 가장 실용적인 방법임을 모두가 공감하고 실천하고 지원하는 그런 날이 속히 왔으면 합니다.