2010년 3월 24일 수요일

개발문서를 만들기는 했는데 업데이트가 안되는 이유

필자는 여러 소프트웨어 회사들의 컨설팅을 진행하면서 먼저 회사의 분석을 위해서 그 동안 소프트웨어를 개발하면서 만들어 놓은 문서를 요구합니다. 사실 문서만 봐도 회사의 개발현황을 대부분 알 수 있습니다.

그런데, 제대로 작성된 문서를 제시하는 회사는 거의 없다시피 합니다. 물론 Wiki나 Google Docs등의 온라인 문서를 포함해서 제대로 작성된 문서는 거의 없습니다. 가끔 문서를 제시하는 회사들이 있기는 하나 수년간 전혀 업데이트를 하지 않아서 쓸모가 없어진 것들 뿐입니다. 

정리를 해보면 다음과 같습니다. 

  • 문서가 아예 없거나 없다시피 한 회사
  • 몇 년동안 업데이트 안된 문서들만 있는 회사 (오늘의 주제)
  • 쓸모없는 문서들을 너무 많이 만든 회사 

야심차게 문서 한번 잘 만들어보겠다고 결심하고 개발 시에 문서를 열심히 만든 후에 소프트웨어는 계속 업그레이드가 되는데 문서는 과거에 머물러 있는 경우에 대해서 얘기를 해보겠습니다.

이런 문서는 죽은 문서입니다.

내용이 맞는지 틀리는지 확인이 안되는 문서는 혼동을 일으킬 수 있습니다.
이런 일이 발생하는 이유는 여러 가지가 있지만 대표적인 이유로는 진짜 문서가 필요해서 만들었다기 보다는 문서가 필요하다고 하니까, 또는 위해서 시켜서 만들었는데, 막상 개발에 크게 도움이 안되고, 단순히 문서를 만들었다는데 의의를 두는 경우가 있습니다. 또, 문서를 너무 잘(많이) 만들어서 소프트웨어가 업그레이드 될 때마다 문서를 갱신하려고 하니 초기 개발 때에 비하여 유지보수 시는 급하게 개발하는 요청이 많아서 미처 문서까지 갱신할 시간이 없는 경우도 있습니다.

이런 경우 모두다 "문서를 위한 문서"인 경우입니다.

문서가 진짜 필요해서 만든 경우가 아니라는 얘기입니다. 역량이 충분히 성숙되기 전에 문서 작성 문화를 정착하려면 어떻게 해야 할까요?

문서를 적게 만들어야 합니다. 

적게 만들면서도 개발에 유용해야 합니다. 그래야 문서를 만드는 일이 프로젝트에 큰 부담이 되지 않고, 추후 업데이트가 가능해집니다.

오래 되어서 쓸모 없어진 문서를 책꽂이에 잔뜩 꽂아 놓고 "옛날에는 문서를 열심히 만들었는데"하고 회상 하십니까? 지금은 그렇게 하고 있지 않다면 효과적이지 않은 방법으로 문서를 만들면서 조직 내에 정착되지 못한 겁니다. 문서 작성을 문화로 정착하려면 "작고 효율적으로 문서 만드는 법"을 익혀야 합니다.

왠만한 크기의 프로젝트도 문서는 한 두 개로 충분합니다. 스펙문서(SRS)와 경우에 따라서 설계문서 정도를 만들면 됩니다. 스펙문서는 요구사항을 분석하는 방법, 꼭 필요한 내용을 적는 방법, 리뷰하는 방법 등을 익혀야 합니다. 요즘은 스펙을 적는 방법에 있어서 다양한 시도들을 하고 있지만, 방법은 조금씩 달라도 꼭 필요한 내용을 빠짐없이 효과적으로 적어야 합니다.

댓글 16개:

  1. 저는 문서를 적게 만드는 것 보다는,
    doxygen이나 ea 또는 여러 툴들을 병행해서,
    문서 작업을 별도로 하지 않아도 항상 up-to-date 하게 만드는 것도 좋은 방법이라고 생각이 듭니다.

    셋팅하는게 귀찮지만 말이죠. 한번 하면 인수인계나, 관리할때 편하거든요.. :)

    답글삭제
  2. 안녕하세요. PatternLoad님

    Doxygen이나 JavaDoc을 이용하는 것은 Low level design 문서 용도로 아주 좋은 방법이죠. 귀찮더라도 이런 규칙은 프로젝트 초기부터 정하게되면 모두 따르도록 어느정도 강제가 필요합니다. 하지만 Doxygen도 업데이트 안하는 경우도 있더군요. - -;

    스펙은 또다른 이슈입니다. 다른 방법이 별로 없습니다. 툴을 이용하는 것도 분석 작업과 업데이트를 대신해주지는 않습니다.

    답글삭제
  3. 저는 문서에 대한 활용도(접근성 및 검색 용이성)가 높다면 그만큼 최신 내용으로 업데이트 될 가능성이 클거라고 봅니다. 이전 회사에서는 항상 MS워드로 문서를 만들고 게시판에 등록시키도록 강요했습니다. 지식검색시스템을 구축해놓고 윗분들이 보기에 좋은 형상을 만들어 놓은거죠. 하지만 실무에서는 검색도 안되고 접근도 용이하지 않았습니다 (다운로드해서 업데이트 해서 다시 올리고..ㅡㅡ)
    전 외부 공개용 문서(메뉴얼등)를 제외하고는 쉽게 활용가능한 툴을 쓰자고 제안했었습니다. 그 방안으로 위키를 제안했었는데 묵살당했죠...ㅋㅋㅋ 로우레벨 문서는 저도 doxygen이 좋은듯..

    답글삭제
  4. 위키는 위키문법의 장벽이 무시 못하고
    그래서 fckeditor + mediawiki 혹은 fckeditor + dokuwiki로 하려고 했는데
    아무도 안하시더라구요 ㅠ.ㅠ


    언젠가 한번 doxygen을 시도해봐야할꺼 같아요..

    답글삭제
  5. 저도 작년부터 설치형 게시판, fckeditor + mediawiki 등등등 문서 정리를 위해서 많은 것을 시도해 보고 있는데 강제가 없으면 중간에 잘 안되더군요.
    그래서, 전략을 좀 수정했습니다. 우선 제가 강제 할 수있는 프로젝트 팀부터 고과에 반영한다고 엄포를 놓아서 조금씩 해보고 있습니다.^^;
    이게 성과가 잘 나오면 전사적 도입도 시도 할 수 있을 것 같아서요....
    항상 제가 고민하는 내용을 시의적절하게 포스팅해 주셔서 감사합니다.

    답글삭제
  6. 예 그렇죠. 스펙은 아무래도 서로 협의하고 조율해야 되는 부분이니깐요. 정말 게으름과 싸워 이기는 문제는 힘들죠.. 전 SparxSystems의 Enterprise Architect로 이러한 환경을 통합할려고 노력하고 있습니다. 툴이 대신 업데이트 해주지 않아도, 어느정도 연관성을 충분히 잡아주는것 같습니다. 물론 이런일도 꽤 번거로운건 사실이죠.. :)

    답글삭제
  7. 변화되는 것은 사람의 활동이고 좀 처럼 변화되지 않는 것은 문서라고 생각해 봅니다.
    으쌰으쌰 해서 잘 된 문서를 만들었다고 해도 이 후에 누가 사용할지 ,또는 어떤 환경요소에 따라서 처음 문서제작의 의미가 살아나거나 또는 죽거나 하는것 같아요.
    경험적으론.. 대 다수의 프로젝트가 말씀하신것처럼 '문서을 위한 문서'가 대부분이었던 것 같습니다. 또는 윗선에 보여주기 위한 방편이 많았던 것이 분명했습니다.

    이를 개선해 보고자.. DDD에서 말하는 Context Map이라던지, Context Integration과 같이 시간이 지남에 따라 문맥이 흐려지는 것을 막기 위한 전략도 어느정도 타당성이 있어 보이지만..(이게 과연 현실적으로 가능할지..이론적인 것만은 아닌지 더 경험해 봐야만 하는 그런 종류의 것인것 같습니다.)
    문서작업을 대부분 싫어해서도 그렇고, 윗선에 보여주기위한 문화라던지, 아니면 문서나 소프트웨어를 인질극으로 삼으려고 하는 사람에겐.. 여간 귀찮은 장애물이 되지 않을까 합니다.

    프로젝트 진행이나 의사소통이 하도 되질 않아, 어느정도 강제적인 강압도 필요한 적도 있었습니다. 하지만만 지속적인 강압은 제일 좋지 않은 결과를 낸 것 같은 아쉬운도 많이 남았습니다.

    항상 저도 이와 같은 고민을 하고 살아요. 어떻게 하면 개선할 수 있을까? 어떻게 하면 모순을 없앨 수 있을까? 정작 중요한것은 개인의 실력일까 아니면 팀웍 콘트롤일까? 신기술이 중요할까 아니면, 타당성 있는 기술이 중요할까 등등..

    규현님 글보면 어찌 제 생각이랑 일치한지~

    답글삭제
  8. SRS가 업데이트가 되지 않고 공유도 안되면서 Test Case 문서랑 매치 하려니 여간 답답한 일이 아닐 수 없지요. 뭐 제가 파견 나가 있는 삼X전자 또한 뭐 해당 문제들이 비일비재 합지요.

    답글삭제
  9. 안녕하세요. 청하님
    문서를 작성하기 어려우면 툴은 더욱 쓰기 어려운 측면이 있습니다. 결국은 어디다기 쓰느냐보다도 무엇을 어떻게 쓰느냐가 핵심입니다. 또한 몇십년전부터 이런 시스템이 없었을 때도 문서를 작성하는데 문제가 있는 것은 아니었습니다.
    저도 이런 시스템을 도입하는데는 긍정적으로 생각합니다. 다만 문서를 먼저 쓰고 리뷰하는 것을 할 줄 알아야 됩니다.

    답글삭제
  10. 안녕하세요. 구차니님
    그렇게 쉽게 바뀌면 정말 좋겠습니다. ^^
    사람들은 바꾸려고 하지 않는 것이 습성입니다. 일단 익숙하지 않아서 불편해하고, 바꾼다고 나아진다는 확인이 없고, 일이 더 많아지고 귀찮아질까봐 바꾸지 않습니다.
    Doxygen도 시도해보고 알아봐 놓는 것은 좋으나 혼자서 열심히 하다가는 혼자만 바쁘고 그 결실은 다 같이 나눠가지다가 금방 포기하고 맙니다. 이런 것은 회사차원에서 강제성을 가지고 추진해야합니다.

    답글삭제
  11. 안녕하세요. koraper님
    전사적인 시행이 어렵다면 시범프로젝트에서 성공사례를 보여주고 설득하는 것도 오래걸리기는 하지만 좋은 방법입니다.

    답글삭제
  12. moova님 안녕하세요.
    그래서 항상 개발 문화를 강조합니다.
    자연스럽게 무슨 일을 하던지 문서화를 하는 수준까지 되어야 합니다.
    꼭 필요한 소수의 문서를 알맞게 만드는 것이지요.
    말로 때우는 방식은 더이상 안됩니다.
    그렇게 문서를 만드는 것이 가장 빨리 개발하는 방법이라는 것을 깨달아야 합니다.

    답글삭제
  13. hoya님 안녕하세요.
    그런 케이스는 거의 주먹구구 방식과 다를바 없습니다. 삼X전자에서는 뭔가 체계를 갖추고 근사하게 개발을 하고 있다고 착각할지 모르지만 실리콘밸리의 구멍가게 소프트웨어 회사보다도 못하다는 것을 아직도 깨닫고 있지 못합니다.
    그러면서 우리나라의 중소 소프트웨어 회사들의 씨를 말리고 있죠.

    답글삭제
  14. 기존 문서에 대한 고정 관념을 좀 버렸으면 합니다.
    프로젝트를 진행 하다 보면 문서 관리에 대해서 반드시 MS의
    word나 ppt 등 특정 파일 포맷으로만 관리 하려고 합니다.
    물론 이런 포맷이 쓰이는 문서도 있지만 이틀에서 벗어나면
    문서가 아닌 것으로 생각해서 도입을 하지 않습니다.
    저런 형식적인 문서보다 차라리 사내에 허접한 게시판 하나
    를 만들어서 히스토리 관리 하는게 더 실용적이라고 생각이
    듭니다.

    답글삭제
  15. 안녕하세요.
    맞습니다. 어디에 적느냐가 아니고 내용을 작성하는게 중요하죠.
    내용을 적을 능력이 없는 사람들은 또 어디에 적더라도 안되기는 마찬가지입니다. 그래서 안된다고 툴만 찾아다기 보다는 무엇을 어떻게 적을지 배워서 꾸준히 해보는 것이 중요합니다.

    답글삭제
  16. 2011년-사설토토제작 판매

    ❤직접 눈으로 확인하시고 결정하세요

    토토사이트 전용 자바 프로그래머와 전문 디자인너 로 구성되어 빠른 제작과 지속적으로 유지보수 및 서버운영까지 풀 서비스 하고 있습니다 한번 고객은 또 다른 분으로 연결되고 서버 및 유지보수에 안정된 관리로 인정받고 제 구매를 해주시는 믿음과 실력으로 인정받고 있는 작업장 입니다 *사설토토

    사용자 패이지

    고급스러운 이미지와 다양한 기능으로 유저에게 보다 신뢰 있게 다가 갈수 있도록 전문 디자인너가 충분한 상당 후 제작해 드립니다 또 요즘 무엇이 인기이고 유행인지를 꾸준히 파악하고 한발 앞서 실행과 유행을 창조하고 있다고 자부합니다
    (참고로 원하시는 사이트 디자인 100% 똑같이 도 가능합니다)


    관리자 패이지

    자동방식과, 엑셀방식. 수동방식 모두 겸비한 최신형 버전입니다
    저희가 직접 자바언어로 제작해서 판매하고 있습니다
    즉 돌고 도는 소스가 아님을 분명히 말씀 드립니다 또 직접 제작한 소스라 수정 및 유지보수가 원활합니다 기능은 너무 많아서 여기서는 생략 하겠습니다 오셔서 상담 받으시고 직접 조작해보시면 됩니다 *사설토토


    계약절차

    1번 제작사이트의 요구사항을 문서로 만들어서 주세요 ( 기능, 디자인, 로고 )
    2번 계약금 100만원 입금
    3번 서버계약 ( 일본서버,미국서버,홍콩서버 선택 )
    4번 세팅 및 디자인 작업
    5번 중도금 100만원
    6번 완성확인 후 잔금처리
    7번 유지보수 및 서버 관리 ( 선택 )


    사이트 제작비용은 총 4백입니다
    서버 관리는 원하시는 분에서만 월 소정에 관리비 받고 관리해 드립니다(도메인 등록, 서버세팅, 서버이전, 아이피 변경, 등등 24시간 관리해 드립니다)
    총 제작기간은 1주일에서 상항에 따라 2주 정도 입니다

    @소스언어는 자바입니다
    @상담시 프로그래머인 제가 통화합니다
    @직원&투자자 소개 및 동업자 연결시켜 드립니다



    msn 메신저 [email protected]

    msn 메신저 모르신 분
    검색창에 msn메신저 설치 검색하시고 설치하시면 됩니다.
    홍콩서버,미국서버,일본서버,사설토토제작

    답글삭제