애자일에서 문서화가 필요할까?

애자일에 문서 작성이 필요할까요?

조대협 (http://bcho.tistory.com)

일본에 계신 정도현님과, 마이크로서비스 아키텍쳐에 대해서 이야기 하다가, 팀이 분할이 되어 있어서, 서로 디자인등에 대한 싱크업(서로 사상과 내용을 공유해서 모두 디자인을 이해하도록 하는것)을 하기가 어렵다는 이야기를 하던중에, 정도현님이 추천해준 글을 보니, 문서화에 대한 이야기가 나옵니다.

http://www.infoq.com/articles/kenji-modeling-agile

이 글인데, 생각해볼만한 가치가 있어서 몇가지생각을 정리해서 남겨봅니다.

마이크로 서비스 아키텍쳐의 장점은 각 서비스를 개발하는 개발자가, 자신이 개발하는 서비스에 대해서 알기가 편하다는 겁니다. 서비스가 작게 쪼게져 있으니 빠르게 이해할 수 있지만, 반대로 전체 시스템에 대한 구조나 사상을 이해하기 어려운 문제가 생깁니다.

실제로 제 경험상, 여러 팀에 서비스를 쪼게주고, 각 서비스에 대한 기능만을 이야기 해주고 서비스를 모아보면, 전체 시스템 사상에 맞지 않는 설계들이 많이 나옵니다.

서비스를 나눠서 개발한다하더라도 전체 팀이 같은 목표와 같은 큰 맥락의 디자인을 공유해야할 필요가 있는데, 제 경우를 먼저 예를 들어보면, 먼저 요구사항을 수집하고 요구사항에 있는 주요 시나리오를 기반으로 전체 컴포넌트와 주요 시스템 흐름을 문서로 정의합니다. 그후에, 분산되어 있는 각팀에 있는 아키텍트들과 싱크업(공유를) 합니다. 주로 전화나 화상회의를 통해서 문서를 화면 공유해서 보면서, 이 시스템의 전체적인 기능은 OO가 있고, 각 기능에 대한 흐름을 컴포넌트들간의 인터렉션 다이어그램을 보면서 쭈욱 같이 따라갑니다. 팀이 많고 분산되어 있다보니, 시간이 많이 걸립니다. (시간대도 틀리기 때문에.)

그러면 전체적인 사상적 공유가 이루어지고, 각 세부 서비스에 대해서 디자인을 각팀에 요청합니다. 그후에, 각  컴포넌트에 대한 디자인이 오게 되면, 검토를 해서 전체 흐름에 문제가 없는지를 검증합니다

개인적으로 문서 작업을 썩 좋아 하는 편은 아니지만, 그래도 최소한의 문서작업은 꼭 필요하다는 생각을 가지고 있었고, 마이크로 서비스 아키텍쳐에 대해서 고민하던중, 실제로 팀간에 디자인에 대한 이해가 틀려서 문제가 생기는 경험도 많이 했고, 문서를 놔두고 설명을 하면 서로 싱크업이 잘못되거나 서로 잘못 이해 하는 경우를 많이 줄일 수 있었습니다.

특히나 영어로 커뮤니케이션을 해야하기 때문에 상대방이 OK 알아들었다고 하더라도, 이해의 수준이 다릅니다.  또는 잘못 이해하고 이해했다고 하는 경우도 많구요. 이해를 확인하기 위해서 문서화를 하면 이 사람이 제대로 이해했는지 못했는지를 확인할 수 있습니다.

문서 작성 원칙

 

애자일 사상은 문서화 방법이나 문서화를 하라 말라에 대해서는 정확하게 가이드 하지 않습니다. 문서화를 최소화 하라고는 합니다만, 하지말라고도 않합니다.

자칫 이해가 잘못되면, 애자일에서는 문서화를 하지 말라는 것으로 이해될 수 있습니다.

지금까지 대략적으로 문서화의 필요성에 대해서 이야기 했는데, 그렇다면 효율적인 문서화 원칙에 대해서 생각해봅시다.

첫번째. “커뮤니케이션을 위한 문서화”를 하라는 겁니다.

애자일에서 효율적인 문서화는 최소한으로 문서화를 하되, 잘못된 문서 관행을 만들어 낸 이유는 보지도 않는 문서를 프로세스에 맞추기 위해서 산더미 같은 문서를 만들어내기 때문에, 문서화를 기피하게 되는데, 대화를 시작하기 위한 문서는 효율성이 높습니다. 그냥 대화를 시작하면 원래 주제를 잃거나 서로 다른 기준점에서 출발해서 이해에 더 많은 시간이 소요될 수 있는데 문서는 같은 기준점을 줄 수 있습니다.

이때 문서를 만들고 그냥 주고..읽어보세요 라고 하면 절대 안되고, 문서를 보고 설명을 해야 합니다.

두번째. “문서는 계속해서 업데이트 되어야 한다”

리뷰나 디자인 변경, 요구 사항 변경에 따라 계속해서 변경되기 때문에 문서는 계속해서 업데이트 되어야 합니다. 이때 중요한것이 변경 관리 인데, 변경된 내용은 문서 배포시 같이 함께 변경 내용을 공시 해서 배포 해야 합니다. 이때는 문서 히스토리 (Revision history) 페이지를 맨 앞장에 추가해서 무엇이 누구에 의해서 언제 어떻게 변했는지 기록해야 합니다. 수십 페이지 문서중에서 어떤 부분이 변화 되었는지를 이야기 하기 힘드니까요.

그래서, 앞에서도 설명했듯이 문서가 변경이 된 후에는 반드시 문서만 전달하는게 아니라 바로 또는 주기적으로 전체 흐름을 리뷰해서 공유를 해야 합니다.

세번째. “업데이트된 문서는 쉬운 방법으로 공유되어야 한다.

문서를 개인 PC에 저장하고 이메일을 통해서 배포하면 문제되는 점중의 하나가 이메일을 제대로 체크하지 않은 사람은 예전 버전의 문서를 계속 보고 있을 가능성이 매우 높다는 겁니다. 그래서 공유된 문서 저장소 개념이 필요한데, 이는 마이크로 소프트의 쉐어 포인트등을 이용하는 것도 하나의 방법이될 수 있고, 드롭박스와 같은 온라인 클라우드 스토리지를 이용하는 방법도 있습니다.

조금 더 진보적인 방법으로는 파일로 문서를 만들지 않고, 아예 위키에 작성해서 온라인으로 실시간으로 공유하는 방법도 있습니다. (아틀라시안 社의 Confluence 위키의 경우, MS-WORD 플러그인을 이용하면, 워드에서 저장하면 자동으로 Confluence에 저장되도록 하는 것도 가능합니다.)

문서에 들어가야 하는 내용

 

그러면 효율적인 문서 작성을 위해서 문서에 들어가야 할 내용을 알아보자. 꼭 문서화 되어야 하는 내용은 크게 3가지 인데,

• ·         주요 사용자 시나리오

• ·         아키텍쳐

• ·         도메인 모델

를 들 수 있습니다. 이를 모두 묶어서 큰그림(Big picture)라고 부르도록 하겠습니다.

이 3가지 모델을 문서화하는 가장 큰 이유는 이 3가지 요소가 전체 시스템을 이해 하는데 가장 핵심 적인 요소가 됩니다.

기존의 전통적인 소프트웨어 개발 방법론은 divide & conquer 식의 접근 방법, 즉 전체 시스템을 조각조각 나눠서 설계 하는 접근 방식을 사용했으나, 근래에는 conquer & divide식의 역행된 방법이 권장됩니다.

“Rather than divide and conquer, an XP team conquers and divides. - Kent Beck”

이러한 접근 방식은 구성원에게 전체의 숲을 보여주고, 각각의 나무를 보게 하는 방식으로.

예를 들어 보면, 큰 도시를 계획하고 만들려고 했을 때 각각 건물을 먼저 디자인한 후에 배치하는 것이 아니라, 전체 도시에 대한 커다란 구도를 잡고 각 구역에 맞는 건물을 디자인하는 것과 같은 이치가 됩니다.

이런 접근을 구체화 하려면 ,전체 시스템에 대한 기능이나 주요 사용자 시나리오를 기술하고, 그 후에, 아키텍쳐를 서술하는데, 아키텍쳐는 주요 기능을 구현하기 위해 필요한 컴포넌트와 그에 대한 관계를 기술하고, 그 다음에는 각 시나리오를 실행하기 위한 컴포넌트간의 플로우(UML에서 activity diagram또는 sequence diagram)를 서술하는 구조가 됩니다.

이와 아울러 시스템을 구성하기 위한 도메인 (개체)들에 대한 모델을 정의하는 것이 필요한데, 데이타 베이스의 ERD등이 대표적인 예에 속한다. 이를 통해서 전체 시나리오가 어떤 개체에 의해서 이루어지는지 그리고 각 시나리오를 구현하기 위해서 어떤 컴포넌트들이 필요하며 컴포넌트들이 어떻게 순서대로 상호 작용을 하는지 이해할 수 있습니다.

공유 방식

자아 그러면 이쯤에서 Infoq.com에 있는 Kenji님의 글중에 있는 내용을 몇가지 살펴봅시다.

문서 공유 방식에 대해서, 좋은 방법을 제시하고 있는 데, “타이거 팀” 이라는 개념이 잘 정리된 개념이라서 이 개념을 기반으로 설명해보겠습니다.

먼저 전체적인 개념을 요약하자면,각 서브 개발팀의 리드들이 타이거 팀이라는 형태로 모이고 큰그림(아키텍쳐,주요 시나리오,도메인 모델)등을 정의하고 이를 같이 리뷰하여 공유 합니다.

<그림. 각 서비스 개발팀에서 타이거팀에 모여서 큰 그림을 공유>

타이거 팀 멤버들이 이해가 다 되면 각 팀으로 돌아가서 큰그림 문서를 가지고 다시 전체 팀에 전파 하는 방식입니다.

<그림. 타이거팀 멤버들이 각팀으로 돌아가서 큰 그림을 각 팀원에게 전파>

이때 타이거팀의 멤버는 각 서브 개발팀에서 기술과 커뮤니케이션에 뛰어난 사람이 되어야 한다.

실제 예를 들어 보면, 여러개의 서비스 컴포넌트 개발팀이 있을때, 각 서비스 컴포넌트 개발팀의 아키텍트가 모여서 치프 아키텍트 아래에서 전체 시스템을 설계하고 토론한 후에, 큰그림 문서를 만들고 나서, 공유 합니다. 이해가 되면 각 팀으로 돌아가서 각 서비스 개발팀의 아키텍트가 큰그림 문서로 모든 팀원에게 전체 시스템 사상과 기능,구조등을 설명하게 됩니다.

각 팀에서 나온 피드백은 아키텍트가 수집해서 검토하고 팀내의 토론을 거쳐서 아키텍트 모임에 의견을 제시 하여 전체에 반영되게 하고, 다시 큰 그림 문서를 업데이트한 후에, 다시 각 팀에 전파를 합니다.

처음 전체 큰그림을 이해하고 전파하는데는 시간이 걸리지만, 큰 그림이 정의된 후에, 세부 조정은 그다지 많지 않은 문서 수정과 공유 시간만으로 가능합니다.

이때 팁은 전체 주요 시나리오를 먼저 설명한 다음에 각 시나리오별로 아키텍쳐 흐름을 따라가는 방법이 효과적입니다.

Kenji님의 문서에서는 이러한 형태의 중앙팀을 타이거팀이라고 소개하였는데, 인터넷을 찾아보니 타이거팀에 대한 정의는 갖가지라서 자세한 정의는 찾아보기 바랍니다.

일반적으로 타이거팀은 뛰어난 사람들을 모아서 프로젝트에서의 문제를 해결하는 소방수와 같은 역할을 하는 개념이나, 또는 프로젝트 초반에 구조와 기술을 잡아내는 선행 개발팀과 같은 개념으로 설명이 되는 경우가 많습니다. 이러한 개념은 예전에도 COE (Center Of Excellence)팀이라는 개념으로 있었고, 애자일 모델에서 각 스크럼팀간의 공유를 위한 스크럼위의 스크럼을 타이거팀으로 정의할 경우에는 예전에 PMO (Project Management Office : 프로젝트 관리 모임. 그러나 PMO는 별도의 분리된 팀 모델을 가짐. 스크럼의 스크럼은 각 멤버들이 각 스크럼에 속해 있고 공유를 위할때만 만나는 형태)나, 커미티 등으로 정의할 수 있습니다.  어쨌거나 애자일에서 COE 팀과 같은 개념이 언급되는것도 재미있는 부분 같습니다. 시간 나시면 꼭 찾아보시기를 권장합니다.

 

제가 개발하고 커뮤니케이션을 하면서 가장 자주 쓰는 말이 있습니다. "Bring all into same page."

모든 참여한 사람들이 같은 컨셉과 같은 이해를 가지고 개발을 할 수 있도록 한다는 말입니다. 이의 중점은 커뮤니케이션이고 이 글에서는 그 방법중의 하나로 최소한의 문서를 이용한 커뮤니케이션 방법에 대해서 설명하였습니다

 

문서는 커뮤니케이션을 돕기 위한 하나의 도구입니다. 도구는 절대 목적이 되면 안됩니다. “문서는 단지 거들뿐..”