소프트웨어 개발자들에게 문서 작성은 고역이 아닐 수 없습니다. 그래서 문서는 소프트웨어를 개발한 후에 후배들에게 소프트웨어에의 스펙과 구조를 설명하기 위해서 작성하곤 합니다. 이런 경우에는 문서의 효용성도 별로 없을 뿐더러 문서가 제대로 작성되었는지 알기도 어렵습니다. 또 개발자들은 기억을 더듬어서 문서를 작성하기도 어려울 뿐더러 이러한 작업은 하기 싫은 고역이 될 수 밖에 없습니다.
소프트웨어를 개발하는데 있어서 필수적인 문서의 대부분은 개발한 내용을 정리하기 위해서 만드는 것이 아니고, 소프트웨어를 개발하는데 필요한 내용을 앞 단계에서 작성하는 것입니다.
즉, 설계를 하기 전에 스펙을 작성하고
구현을 하기 전에 설계서를 작성하고
테스트를 하기 전에 테스트 계획 및 TCL(Test Case List)를 작성합니다.
하지만 현실에서는 이렇게 작성된 문서를 가지고 다음단계 작업이 잘 안 된다는 문제가 있습니다.
즉, 다른 개발자가 작성한 스펙을 가지고 설계 및 구현(코딩)을 할 수가 없는 경우가 대부분입니다.
스펙을 제대로 작성하려면 남이 설계할 수 있을 정도로 상세하게 적어야 하는데, 잘못하면 백과사전이 되고 또는 흔히 빈약한 스펙서를 작성합니다. 이렇게 되면 스펙을 작성한 사람이 또 설계자에게 계속 스펙을 설명해줘야 합니다.
이 글을 읽고 있으면서 이것이 뭐가 문제라고 생각하신다면 이미 가내수공업식 개발에 익숙해지신 겁니다. 한 개발자가 스펙도 작성하고 설계, 구현, 테스트를 모두 다하는 이런 가내수공업식 개발은 회사는 성장의 한계에 부딪히고, 개발자는 성장하지 못하는 악순환에 빠지기 쉽습니다.
개발문서는 그 문서를 보고 다음단계의 개발자들이 충분히 일을 진행할 수 있을 정도로 상세해야 합니다.
따라서 상세화 정도는 상황에 따라서 다르다는 것을 알 수 있습니다. 설계자가 해당 제품에 대해서 빠삭하게 알고 있으면 기능스펙을 적당히 적어도 문제가 없을 것이고, 신입사원에게 일을 시키려면 좀더 자세히 적어야 할 것입니다.
또한, 좀더 작은 양으로 이해 가능한 문서를 작성하려면 소프트웨어를 다양한 뷰에서 바라보고 적어 주는 것이 좋습니다. 따라서 스펙을 작성할 때는 소프트웨어를 인터페이스에서 바라본 모습, UI에서 바라본 모습 그리고 기능, 비기능적인 내용을 적어주면 기능에 대하여 많은 양을 설명한 것보다 더 이해하기 쉽습니다. 설계에 있어서도 소프트웨어의 아키텍처를 데이터 관점, Flow 관점, 시간의 흐름, 시스템의 상태 등 다양한 관점에서 바라본 모습을 적당히 표현해 주는 것이 하나를 자세히 적어 주는 것보다 좋습니다.
매우 추상적인 글을 적어 놓은 것 같지만, 실제 개발문서를 제대로 적기 시작하면 잘 적었는지? 못 적었는지는 명확하게 구분 됩니다. 작성된 문서를 가지고 다음 단계 개발자들이 별 무리 없기 개발을 할 수 있고, 문서가 거의 바뀌지 않는다면 잘 작성된 것이고, 그렇지 않으면 잘 작성되지 않은 것입니다.
그래서 이를 위해서 기법을 쫓기 보다는 실제로 필요한 것이 무엇인가 생각하고 실질적인 접근이 필요합니다. 잘못 익힌 기법은 독이 될 수 있습니다.
문서가 실용적이어야 한다는 의미는 공감합니다만,
답글삭제> 문서가 거의 바뀌지 않는다면 잘 작성된 것이고, 그렇지 않으면 잘 작성되지 않은 것입니다.
이 부분은 일반적인 이야기가 아니지 않나 생각됩니다. 코드는 문서보다 훨씬 빠르게 바뀌기 때문에 문서는 뒤쳐지게 되어있는데, 아마도 말씀하신 의미상으로는 문서를 이런 변화까지 수용하게 적어야 된다는 것이 아닐까 추측되는데, 그건 잘 작성된 기준으로 생각하기에는 적합한 기준이 아니지 않나 생각됩니다. 문서가 바뀌기 때문에 잘 작성하지 않았다는 것은...
또한, 다음 단계(?)의 개발자가 이를 활용할 수 있는 프로젝트가 있는 반면, 그렇지 않은 프로젝트도 많이 있기도 한 것 같습니다.
charlz님 안녕하세요.
답글삭제좋은 의견 감사합니다. charlz님의 댓글을 보면 "문서"라는 말을 가지고도 서로 다른 이미지를 그리고 있다는 생각이 듭니다.
예를 들어서 스펙서를 기준으로 보면 설계단계나 구현단계에서 스펙서가 바뀌는 것은 스펙이 바뀐 것이고, 그 변경에 대한 비용을 몇곱절로 치뤄야 합니다. 하지만 개발 기간내에 스펙이 전혀 바뀌지 않는 프로젝트는 찾아보기 힘들죠. 하지만 변경을 최소화는 해야 합니다. 설계가 진행되고 코드가 진행됨에 따라서 스펙서를 바꾸지는 않죠.
그리고 설계서의 경우에도 코드가 진행됨에 따라서 아키텍쳐나 인터페이스의 변경이 있기 전에는 설계서가 변경되지 않습니다. 문서와 코드가 같이 발전해 나가는 경우는 분석, 설계, 구현단계가 적당히 밍글된 형태일 수도 있습니다. 사실 크고 작은 많은 프로젝트가 이렇게 진행되고 성공적으로 잘 끝나기도 합니다. 하지만 이런 방법으로 계속 성장하기는 어려움이 있습니다.
사실 문서가 잘 작성되었는지 판단하기는 대단히 어렵습니다. 그래서 그 한방법을 언급해 봤습니다.
제가 항상 주장하는 것은 개발자들이나 개발사들의 현재 상황에 따른 전투적인 대응방법이 아니고 개발자들이 꾸준히 성장하고 실력도 향상되며 현재 프로젝트를 잘 수행해내기 위한 원론적인 방법들이 주류를 이룹니다. 그런 관점으로 읽어주세요.
charlz님의 의견과 같은 여러 관점은 제가 많은 도움이 되네요. 감사합니다.
문서라 지긋지긋하지요.
답글삭제정말 돈받고 만드는 프로덕트로서의 문서들은 가끔 종이값과 타이핑값을 받기 위해 만드는거 아닐까 하는 생각이 들곤 합니다. 그래서 도큐멘트도 아니고 산출물이라고 하는게 아닐까 생각하죠. ^^
SI성 프로젝트를 많이 하다보니 몇십종의 산출물들이 과연 필요나 할까 싶을떄가 많기도 하고, 왜 보지도 않고 쓸데도 없는 문서를 주구줄창 만들어야 할까 싶습니다.
경험적으로 생각해보면 산출물은 의사전달을 위한 문서, 생각을 정리하기 위한 문서, 점검을 위한 문서 세종류가 있는 것 갑습니다. (그냥 제 기준입니다.)
무엇을 위해서 작성을 하는지가 중요한 것 같은데.. 문서 프레임에 압도당할때가 만은데요. 잘하지는 못하지만 고객이나 내부 팀원이 쓸 수 있을 만한 표현력이 들어가면 문서의 프레임이야 얼마든지 고칠 수 있지 않나 싶네요. ㅎㅎ
뭐 항상 만들고 나면 이것 저것 한방에 보고 싶다는 욕심에 덕지덕지 붙여넣다가
질려서 흐지부지 되는 경향이 있어서.
될 수 있으면 간략한게 좋지 않나 생각이 드네요.
특히나 고객의 요구사항이 수시로 변할떄는 말이죠.
산더미같이 많은 문서를 만드는 프로젝트들은 아주 잘못된 관행입니다. 소프트웨어 개발에 대해서 잘 모르는 고객이 거대한 방법론에 있는 문서를 무작정 다 요구하곤 합니다. 그 방법론에서도 문서를 다 만들라고 하지 않는데도 잘못 적용하는 것이지요.
답글삭제하지만 개발사 입장에서 고객이 요구하는데 안만들 수는 없는 노릇이지요. 수많은 문서 중에서 실제 개발에 필요한 문서는 소수에 불과합니다. 그런 문서만 제대로 만들고 나머지 프로세스나 관리를 위한 문서들은 최소한의 노력만 들이는 것이 좋습니다.