'문서화'에 해당하는 글 1건

336x280(권장), 300x250(권장), 250x250, 200x200 크기의 광고 코드만 넣을 수 있습니다.
많은 프로젝트에서 문서화를 합니다. 문서화는 프로젝트 중간에 진행되기도 하지만 보통 프로젝트 종료 후 진행 됩니다. 제가 보기에 문서화의 필요성에 대해서는 많은 사람이 공감하고 있는 듯 합니다. 그렇지만 그 사람들에게 문서화를 통해서 만들어진 문서가 실제로 도움이 되었느냐 묻는다면 얼마나 고개를 끄덕일지 모르겠습니다. 우리는 경험적으로 그동안 보아왔던 문서들은 큰 도움이 되지 않는다는 것을 알고 있습니다. 도대체 왜 이러한 일이 발생하나요? 

제가 생각했던 가장 큰 문제는 문서에 너무 많은 내용을 담으려고 한다는 것입니다. 보통 문서화에 할당되는 시간은 한정되어 있습니다. 그런데 보통 문서화를 요구하는 사람들은 개발 프로세스로부터 정의 된 몇 가지 고정된 필수항목들을 요구합니다. 이런 경우 한정된 시간에 문서화를 완료하려하다보면 자연스레 구색만 맞춘 문서가 만들어집니다. 전달하고 싶은 내용이 있어도 적절한 항목이 없거나 시간이 없어서 못 만드는 경우도 있습니다. 이렇게 만들어진 문서를 읽다보면 어려움을 느낄 때가 많습니다. 조금 읽어보면 내가 필요로 하는 정보는 찾을 수 없고 다른 정보만 잔뜩 들어있기 때문입니다.

그 다음은 변화하지 않는 문서입니다. 즉, 소프트웨어는 변했는데 문서는 변화하지 않는 경우입니다. 이런 문서에 근거하여 어떤 일을 진행하다 많은 시간을 허비하거나 문제를 일으키는 경우가 있습니다. 왜냐하면 문서의 내용이 잘못 되어있기 때문입니다. 사실 이런 문서라면 아예 없는 것이 나을 수도 있다고 생각합니다. 왜냐하면 문서가 없다면 해당 일을 진행할 때 자체적으로 조사를 해서 더 원활히 일을 진행할 수도 있기 때문입니다.

사실 위에서 얘기했던 왠만한 개발자라면 누구나 알만한 매우 기초적인 문제점들에 대한 지적입니다. 오히려 중요하지만 제가 미처 언급하지 않은 문제점이 있을 수도 있겠지요. 아무튼 위와 같은 문제점을 지적했느니 저는 제가 생각하는 효율적인 문서화에 대해서 얘기해보고자 합니다.

제가 생각하는 효율적 문서화의 구조는 크게 두 가지 부분으로 나눌 수 있습니다. 첫 번째 부분은 잘 변하지 않는 즉 가장 추상화 된 부분을 다루는 소프트웨어 구조에 대한 문서입니다.

예)
설계 배경
설계에 대한 근거
주요 구성요소의 역활

위와 같은 내용은 거의 변하지 않습니다. 왜냐하면 소프트웨어를 만들 때의 배경과 설계 근거는 이미 과거에 일어난 사실이기 때문입니다. 또한 소프트웨어의 주요 구성요소도 정말 큰 변화가 없는한 그대로 유지됩니다. 이것은 이 문서가 한번 만들어지면 문서의 유지보수에는 더 이상 크게 신경쓰지 않아도 된다는 것을 뜻합니다.

위 문서의 목표는 유지보수 하는 개발자가 문서를 보았을 소프트웨어에 대한 전반적 이해를 가질 수 있게 하는 것입니다. 만약 해당 개발자가 이 문서를 통해 제대로 된 이해를 갖게 할 수 있다면 나머지 세부적으로 파악해야 할만한 내용은 해당 개발자가 코드를 보며 빠르게 파악할 수 있을 것입니다. 그렇지만 누군가는 이런 의문을 제기할 수도 있습니다.

당장 1시간 안에 접근 허용 IP 목록을 추가해야 할 때는 어떻게 합니까? 구조를 아직 파악하지 못했다면요? 혹 구조를 파악했다 하더라도 신속히 수행하기 힘들지 않나요?

예, 이런 문제를 보완하기 위해 두 번째 문서가 존재해야 합니다. 윈도우 운영체제 이론에 정통한 교수님이라 하더라도 윈도우의 창의 폰트를 바꾸는 법을 찾기 위해 1시간 이상 헤맬수도 있는 것이죠.

위와 같은 부분은 운영 문서에서 다루어야 합니다. 운영 문서는 철저하게 실용적이고 가장 구체적으로 구성되어 있어야 합니다. 또한 운영하는 입장에서 빈번히 필요할 만한 상황을 고려하고 있어야 합니다. 예를 들자면 아래와 같은 것들이 될 수 있습니다.

서버 시작하고 정지하기
접근 IP 추가하기
컴포넌트 추가하는 절차 및 방법

이렇게 두 개의 문서가 구성된 후 유지보수 하는 개발자는 선택을 할 수 있습니다. 해당 소프트웨어의 이슈가 많지 않아 최소한의 운영만 해주면 된다면 굳이 시간을 들여 구조에 대한 문서를 보지 않고도 운영에 대한 문서를 필요 시마다 참고할 수 있습니다. 만약 운영 문서에서 다루지 않는 문제가 발생한다면 스스로 해결 후 문서를 수정해주면 됩니다. 하지만 만약 해당 소프트웨어에 이슈가 많고 장기적으로 많은 수정과 개선이 필요하다면 구조 문서를 숙지하면 됩니다. 구조에 대한 확실한 이해를 바탕으로 소프트웨어를 견고하게 유지보수 하고 개선해 나갈 수 있을 것입니다. 

이러한 방식으로 문서화를 했을 때 서두에서 제기했던 문제들도 어느정도 해결 될 수 있습니다. 첫째로 얘기했던, 문서에 너무 많은 내용을 담으려 할 때 생기는 문제는 위에서 제가 얘기한 구조를 채택함으로써 자연스레 해결될 수 있습니다. 두 개의 문서만 만드는 접근 방식은 그동안 보아왔던 보편적 문서화와 비교할 때 문서량이 매우 적습니다. 또한 특별한 필수 형식을 요구하지 않기 때문에 문서화를 하는 사람은 자신의 판단에 근거하여 전달하고 싶은 부분을 중점적으로 문서를 만들 수 있게 됩니다.

두 번째 변화하지 않는 문서의 문제 역시 많이 경감될 수 있습니다. 왜냐하면 위 구조의 경우 운영문서만이 변화에 대한 영향을 받기 때문입니다.


#그림1. 소프트웨어 문서화 대상

결론적으로 제가 주장하고 싶은 부분은 위 그림과 같이 소프트웨어의 양극단만을 문서화 하자는 것입니다. 소프트웨어의 개발 흐름을 보면 아이디어로 부터 시작되어 소프트웨어 구조 작업이 시작 됩니다. 그 후 구현 코드가 만들어지고, 마지막으로 구현 코드를 쉽게 작동시킬 수 있는 운영 도구가 나옵니다. 이 때 우리는 구현 코드와 같이 자주 변하면서도 문서화 했을 때 큰 가치를 주지 못하는 중간 영역을 문서화 하려고 노력하기 보다는 잘 변하지 않는 소프트웨어 구조와 구체적인 운영 도구에 대한 설명에 집중함으로써 최소한의 노력으로 최대의 효과를 거둘 수 있을 것입니다.

2009/03/16 ~ 2009/10/19

수정 이력
2009/10/19 22:30 : 전반적으로 문장을 부드럽게 고침.

WRITTEN BY
차민창
르세상스 엔지니어가 사회를 이끌어나가는 상상을 하며!

,