문서화 딜레마
2010/11/11 17:22 by 전규현
All of Software 블로그를 RSS Feed에 등록을 해 놓으시면 편리하게 받아보실 수 있습니다.
RSS Feed
RSS Feed
우리나라 소프트웨어 회사 중에서 문서를 제대로 작성하고 있는 곳을 찾기란 그리 쉬운 일이 아닙니다.
제대로 작성한다는 의미는 꼭 필요한 만큼 적절히 효과적으로 작성하는 것입니다.
대부분의 소프트웨어 회사는 변변한 문서 하나 없이 개발을 하고 있고 반대로 소수의 회사는 불필요한 문서를 잔뜩 만들어서 오히려 효율성을 떨어뜨리고 있습니다.
물론 제대로 하고 있는 회사도 있지만 그 수는 극히 적습니다.
대부분의 여러분들도 겪은 현상이거나 앞으로 겪을 것입니다. 변변한 문서하나 제대로 만들지 않고 소프트웨어를 개발하고 있는 회사는 구멍가게 이상의 규모로 성장하기 어렵습니다. 회사의 규모가 커지면서 문서가 부족하면 커뮤니케이션 비용이 기하급수로 증가하기 시작합니다. 회사가 작았을 때 숨어있던 문제들이 마구 터져 나오기 시작합니다.
이미 문제가 되기 시작한 이후에 문서를 만들어보자는 결심을 하기도 합니다. 하지만 이미 제품을 다 개발한 이후에 유지보수하는 제품의 문서를 제대로 만드는 것은 거의 불가능합니다.
문서의 주목적은 소프트웨어를 제대로 개발하기 위한 것이지 유지보수를 위한 것이 아닙니다. 유지보수 단계에서 문서를 만들면 문서에 많은 내용이 빠지게 되고 의욕도 떨어지게 됩니다.
하지만 문제는 또 다른 곳에 있습니다. 그동안 제대로 문서를 만들지 않고 개발을 해온 개발자들이 문서를 만들자고 결심만 했다고 해서 문서를 작성하는 실력이 갑자기 생기지는 않습니다.
즉, 문서를 만드는 실력이 부족하다는 겁니다.
본인들은 문서를 잘 작성할 줄 아는데 바빠서 만들지 못한다고 합니다. 그래서 시간만 있다면 문서를 언제든지 만들 수 있다고 합니다. 이렇게 말하는 것자체가 문서를 제대로 만들어 본적도 없고 문서를 만들지도 모른다는 반증입니다. 왜냐하면 바쁠 수록 문서를 적절히 잘 만들어야 프로젝트 시간이 단축되기 때문입니다.
그러다보니 제대로 된 문서도 없이 유지보수가 뒤죽박죽이 되어서 항상 고참 개발자들이 유지보수에 매달려야 해서 계속 바쁘게 되고 그러다보니 문서를 제대로 만드는 실력을 향상할 기회는 또 없게 됩니다. 새로운 프로젝트를 시작해도 또 과거의 방식으로 문서도 제대로 없이 개발을 하게 됩니다.
개발자들이 코딩을 잘하는 이유는 수년에 결쳐서 코딩을 계속 해 왔기 때문입니다. 철저히 훈련이 잘 되어 있습니다. 다들 실력차이는 나지만 코딩을 못하는 개발자는 개발자도 아니죠.
그렇듯 문서도 계속 작성을 해봐야 잘하게 됩니다. 처음부터 기가막히게 멋진 문서를 만들 필요는 없습니다. 항상 기록을 남기는 습관을 들이는 것도 문서를 잘 작성하는 실력을 키우는데 좋은 도움이 됩니다.
물론 프로젝트에서 필요한 문서는 단순히 글을 잘 작성한다고 되는 것도 아닙니다. 하지만 글을 쓰는 습관이 출발점입니다. 그리고 프로젝트에서 필요한 문서는 원래 선배들이 제대로 작성을 해 왔다면 문서를 리뷰할 때 참석해서 문서 작성 방법을 배울 수 있습니다. 하지만 안타깝게도 선배에서 문서 작성법을 배울 수 있는 회사는 우리나라에 그렇게 많지 않습니다. 대부분은 스스로 해 나가야 합니다. 이에 관련된 책들의 도움을 받는 것도 방법 중 하나 입니다.
명심할 것은 욕심을 부리지 않는 것입니다. 너무 많은 내용을 완벽하게 적으려고 하면 오히려 금방 질려서 포기하게 됩니다. 또한 바쁘니까 나중에 몰아서 만든다는 생각도 버려야 합니다. 문서는 지금 이순간이 아니면 만들 수 없습니다. 지금 필요한 만큼만 적당히 적게 만들어야 합니다.
* 이 포스트는 blogkorea [블코채널 : 꿈꾸는 소프트웨어 개발자 세상] 에 링크 되어있습니다.
Image by Damon Duncan
'개발문화' 카테고리의 다른 글
| 매일 불난 호떡집 같은 회사 (중요한 일 vs. 시급한 일) (14) | 2011/01/03 |
|---|---|
| 해외에 소프트웨어를 팔려면 이것이 꼭 필요하다. (12) | 2010/12/14 |
| 문서화 딜레마 (20) | 2010/11/11 |
| 내가 지금 하고 있는 일의 가격 (6) | 2010/11/02 |
| 개발자를 잘못 채용하는 방법 (22) | 2010/04/19 |
| Google을 이끄는 힘 (7) | 2009/10/30 |
Trackback Address: http://allofsoftware.net/trackback/192
문서화 정말 어렵더라구요. 4년차만에 처음으로 개발하기 전에 설계하면서 문서부터 만들고 있는 중인데, 이 정도밖에 안됐나 하는 자괴감이 들더라구요. 갑자기 또 속상해지네. 크크크. 10년차 되서 스펙때문에 또 좌절하면 어쩌죠. 스펙까지 익숙해지려면 보통 몇년 걸리나요? 빌 조이같은 천재들 말고요.
안녕하세요. 김재호님
스펙은 가장 작성하기 어려운 문서입니다.
요구사항 분석 능력이 있어야 하고, Domain도 잘 알아야 하고, 문서도 잘 작성해야 합니다.
제대로 적는데는 기본적으로 3~4년은 걸리고 10년이 지나고 20년이 지나도 꾸준히 실력이 증가하는 소프트웨어를 개발하는데 있어서 가장 어려운 분야입니다.
빌조이 같은 천재라고 해도 결코 처음부터 스펙을 잘 적을 수는 없습니다.
문제는 스펙을 적는 방법을 배우기가 어려운 거죠.
이에 관련된 책들의 도움을 받아야 한다고 하셨는데 혹시 좋은 책을 추천해 주시는 것은 가능하신지요?
안녕하세요. godway님
우리나라 책중에서는 제가 쓴 "소프트웨어 개발의 모든 것"을 추천합니다. 그리고 외국책 중에서는 Requirement Engineering으로 검색을 해보시는 것이 좋겠습니다.
책을 보는 것은 도움이 되기는 하지만 책만 보고 제대로 작성하는데는 매우 오랜 시간이 걸립니다.
소프트웨어 개발의 모든 것, CodeCraft, 조엘온 소프트웨어 등등을 읽으면서,
"스펙 문서 만드세요."
라는 말을 볼 때마다, 그렇지요 옳은 말씀이지요 하면서 읽었습니다.
실제로 실천하려 하니 참으로 어렵다는 생각을 많이 해 봤습니다.
문서를 여러개를 짧게 만들어야 하는지, 길게 하나로 만들어야 하는지...
여기에는 이것이 들어가도 되지만, 저기에는 이것이 들어가면 안되는지...
이것들 고민하는 것이 일이고 실력이라는 생각 역시 들었습니다.
하지만 전에 한 번 분석 설계 구현의 순서로 만들기를 실험해 봤을 때,
시간이 확실히 줄어들었던 기억이 있어서
이젠 꼭 지키려고 노력합니다.
정말
"건강하게 살려면, 나쁜 것들 드시지 마시고, 운동 열심히 하세요"만큼이나 어려운 일이 문서화인듯 합니다.
안녕하세요. 주의사신님
문서는 쪼개나 합치나 같은 겁니다.
관리가 편하려면 하나의 문서로 만드는 것이 좋지만, 한 섹션이 너무 크면 문서를 나눠도 좋습니다.
단 문서를 나눌 경우에는 문서에 Link를 걸어야 하는데 Link된 문서는 바로 열어 볼 수 있도록 회사의 문서관리시스템이나 소스코드관리시스템에 등록해서 그 Link를 추가해야 합니다.
좋은 경험을 가지고 계시네요.
꾸준히 계속 적어나가면 매번 실력이 늘어가는 것을 느낄 수 있을 겁니다.
안녕하세요, 전규현님 오랜만입니다.
문서를 만들겠다고 달려드는 데서 부터 문서화 작업이 힘들어 지는 것이 아닌가 생각합니다. 요즘 인기있는 지속적 통합이나 지속적 배포같은 부분에서 말하듯이 문서화도 짧게 지속적으로 문서를 만들어 나가야 하지 않을까 생각합니다. 시스템 만들어 놓고 테스트 시작하거나, 통합을 시작하거나 하면 큰 문제가 생기니 짧게 짧게 작은 양에 대한 작업을 하자는 것처럼 문서화도 그 때 그 때 노트 형식으로 적어 놓으면서 발전 시켜 나가는 방법도 나쁘지 않은것 같습니다.
안녕하세요. Jake님
과유불급이라고 생각합니다.
그래도 여전히 문서 만들기를 지극히 싫어 합니다.
그래서 최근에 Agile에서는 문서를 안만들어 되는 것으로 착각하고 혹 하기는 합니다.
문서를 만드는 방법이 다를 뿐이죠.
문서는 만드는것보다도 계속 업데이트하는게 중요한것 같더군요..
실제로 버전이 올라가다 보면 문서와 소스내용이 틀려 낭패보는 경우도 가끔 있구요..
저술하신 "소프트웨어 개발의 모든것"을 봤지만 제가 말씀드린 경우의 해결책은 못 본것 같은데요..(기억을 못하는지도..)
문서의 버전업을 어떤 형식으로 진행할 수 있는지 방안이 있으시면 조언 부탁드립니다.
또 문서없이 wiki만 사용하는 경우 문제점이 있을까요? (요즘 문서의 버전문제때문에 wiki를 검토중이라서요..)
언제나 좋은 글 감사합니다..
안녕하세요. 무혹님
그래서 문서는 최대한 적게 만들어야 합니다.
제 책에서도 문서의 업데이트에 대한 내용이 있습니다.
책의 내용을 보면 이와 관련된 내용이 몇가지 있습니다.
문서는 업데이트가 어렵기 때문에 꼭 필요한 문서만 만들고 SRS는 꼭 업데이트 하라고 하고 있습니다.
또한 설계문서는 완벽하게 업데이트하기 어렵다고 설명하고 있습니다.
설계문서는 구현을 하기 위해 필요한 것이기 때문에 나중에 변경되는 것은 모두 업데이트 하기 어렵습니다.
그래서 Doxygen이나 JavaDoc을 잘 이용할 것을 설명하고 있습니다.
설계에서는 그렇기 때문에 인터페이스를 최대한으로 깔끔하고 간단하게 만드는 것이 좋습니다. 너무 얽히섥히 섞인 인터페이스는 나중에 바뀌더라도 관리가 잘 안됩니다.
약간 다른 이야기 이기는 합니다만..
대체로 글 잘 쓰시는 분들이 코딩 역시 잘 하시더군요
후배들 코딩 스타일을 글 쓰는 유형에 비교하면 다음 3가지로 간추려 지는데..
-시인 타입: 이해하기 힘들다. 잘 돌아간다.
-이면지 제작자: 이해하기 힘들다. 잘 안 돌아간다.
-기자 타입: 이해하기 쉽다. 잘 돌아간다.
요새는 코딩하기 전 과제 계획서 또는 일정표 등 문서 부터 써 보라고 합니다.
글을 쓰는 모습을 보면 이 사람이 코딩을 어떻게 하겠다 대충 알 것 같더군요
더불어 우리가 수학 논문을 많이 쓰기 때문에 증명 숙제 한거나, 쓴 논문을 보면 이 녀석이 위 중 어느 타입이구나 감이 오더군요.
csj님 안녕하세요.
전적으로 동감합니다. Coding도 하나의 언어잖아요. ^^
안녕하세요 ~ 좋은 글 잘 봤습니다
저는 컴퓨터와는 전혀 관련이 없지만 말씀하신 내용은 학생부터 나이든 할아버지 할머니까지 도움이 되는 거 같아요
뭐 개인적으로는 연구노트를 꾸준히 제 때에 쓰고, 제 때에 다시 살펴보는 게 얼마나 어려운 지 느끼고 있네욤 ㅡ _ㅡ;;
안녕하세요. Playing님
세상만사 다 비슷한가 봅니다.
한번 작성이 아니라 계속 업데이트 해야 하고
그걸 여러 사람과 공유/동기화 하는게 가장 힘든걸 보면
Trac 등에서 위키로 문서화 하는 추세가 바람직 할수 밖에 없는것 같아요.
안녕하세요. 구차니님
Word로 작성을 하던 Wiki를 이용하든지 큰 상관은 없을 것 같습니다. 중요한 것은 문서를 작성하는 것이고 그 내용이 더 중요하다고 생각합니다. 어디에 적느냐는 서로 장단점이 있는 것 같습니다.
내용이 중요하다는 의미는 설계문서를 작성할 때 UML을 이용하느냐 Doc로 작성하느냐 노트에 연필로 작성하느냐보다는 "설계"자체를 잘 하냐가 더 중요하듯이 어차피 내용을 잘 모르면 어떠한 툴을 가져와도 의미 없는 문서가 됩니다.
그래서 선배들이 작성한 문서를 리뷰에 참석해서 꾸준히 배워나가는 것이 문서에 무엇을 적어야 하는지 배우고 또 어떻게 적어야 하는지 어떻게 리뷰를 해야 하는지 익힐 수 있습니다.
또, 무엇은 적을 필요가 없는지도 자연스럽게 배우게 됩니다.
현재 그런 환경이 아니라면 누군가가 먼저 시작을 해야겠죠. 항상 선구자는 힘든 법입니다. ^^
선구자는 힘들다는 말, 무척 공감이 갑니다.
"내가 무엇을 해 보겠다" 할 때 대부분 반응은 "왜 귀찮게 그런 걸 하냐"가 대다수 더군요
가끔은 왜 이걸 해야 하는지 설득하는게 더 힘들 때도 있습니다.
여하튼 최근에 작은 프로젝트 팀장이 되어 이것 저것 해 보려고 하다보니 고민이 많네요.
그런 경우는 무엇을 하고 무엇은 지금은 무리인지를 판단하는게 중요합니다.
사실 이런 판단이 가장 어려운 판단 중에서 하나입니다.
그럴때 주변의 선배나 전문가에게 물어보는 것이 가장 좋습니다.
본인 스스로 판단하는 능력이 생기려면 이러한 경험을 모두 해 본 후 일겁니다.
참 힘들죠~
현재 3명이 작은 프로젝트를 진행 하고 있습니다.
문서화.. 참 힘들네요.. ㅠ
안녕하세요. 철이님
혹시 문서화를 왜 하려고 하시나요?
문서를 작성하면 프로젝트의 기간이 줄어든다는 것을 믿고 계시나요?
이것을 경험을 통해서 알고 있지 않으면 문서를 만들기 정말 어렵습니다.
대부분은 몇번 문서를 만들다가 프로젝트 시간만 더 걸리고 문서가 사장되기 일쑤입니다.
이런 경우는 필요없는 문서를 만들거나 문서를 잘못 만들기 때문인 경우가 많습니다.
그래서 제 책에서는 설계 문서보다더 스펙(SRS)문서를 만들라고 권하고 있습니다. 또한 뒤늦게 만드는 문서는 필요없고 프로젝트를 더 지연시키므로 만들지 말라고 하고 있습니다.
또 중요한 것은 문서는 가능하면 적게 만드는 것이 가장 좋습니다.