본문 바로가기

개발

개발자를 위한 개발자에 의한 문서 만들기

얼마전 화면을 하나 개발할 일이 있어 간만에 코딩을 한 적이 있습니다. (코딩은 언제나 즐겁습니다 ^^)

요즘은 거의 코딩을 하지 않고 살기 때문에 코딩이 무뎌졌을 거라 걱정했었는데, 다행히 생각한 것 만큼 그리 힘들지 않더군요.

문제는 회사 내 우리 팀(클라이언트 화면 개발팀)이 만든 각종 컨트롤을 다루면서 생겼습니다.

화면에서 다루어야 하는 각종 컨트롤들이 있는데 이 컨트롤을 다루는 방법에 대한 문서화가 전혀 안되어져 있어서 실제 핵심이 되는 알고리즘을 만드는 시간보다 컨트롤에 대한 사용방법을 찾느라 대부분의 시간을 허비했습니다.(뭐 원래 윈도우 프로그램 개발하는 데 UI 개발에 걸리는 시간이 훨씬 많은 편이라는 건 인정합니다만..)

회사에서 자체적으로 만든 콤보 컨트롤, 달력컨트롤, 라디오 컨트롤, 리스트컨트롤 등 수 많은 컨트롤들이 있는데 하나같이 문서화가 되어 있지 않아서 사용법을 알기 위해서는 전체 소스를 검색해서 컨트롤을 사용한 화면을 찾아 내고 해당 화면의 소스를 copy & paste 해서 돌려보고, 잘 안되면 또 수정하고, 디버깅해 보는 방법밖에 없었습니다.

차라리 윈도우 기본 컨트롤이라면 간단히 MSDN 을 찾아 보거나 code project code guru 사이트를 뒤져 보면 될 일지만, 사내에서 자체 개발한 컨트롤은 어디에도 문서를 찾을 수가 없기 때문에, 이런 식으로 샘플을 찾아 사용용도를 짐작해서 복사하는 방법밖에 없었는데요. 왜 우리 팀에는 제대로 된 개발자를 위한 문서가 없는 것일까요 --;; 이거 저희 팀에만 있는 문제인가요?

 

개발자를 위한 문서가 절실합니다.

 

개발자들에겐 제대로 된 개발 자료는 개발 시간을 단축하고 다음 프로젝트를 순조롭게 진행하기 위한 필수 항목입니다.

특히 큰 프로젝트라면 자체 개발한 수많은 클래스와 라이브러리 모듈들이 있는데 이에 대한 문서화가 없다면

-       새로 들어온 개발자는 인맥을 통해 물어 물어 선배님들로부터 정보를 얻는 수 밖에 없습니다.

-       잘못하면(팀 내 커뮤니케이션이 잘 안 된다면) 동일 코드를 재 작성할 수도 있게 됩니다.

-       프로그램 개발 시간이 늘어 납니다. 문서가 안되어 있기 때문에 해당 소스의 사용법을 코드 차원에서 살펴 봐야 하고 어떤 점을 주의 해야 하는지 알 수가 없고 다만 짐작에 의해 프로그램할 수 밖에 없습니다.

-       불필요한 코드가 늘어 납니다. 앞서 얘기한 것처럼 문서화가 되어 있지 않으면 최적 소스를 만들어 낼 수 없고 단순히 선행 프로젝트의 소스를 COPY & PASTE 해야 하기 때문에 불필요한 코드가 같이 묻어 가는 경우가 많습니다. 이 코드를 또 누군가 복사해 간다면 점점 요지경이 되는거겠죠.

-       본인이 만든 컨트롤도 몇 개월이 지나면 사용법을 잊어 버리는게 당연합니다. 어처구니 없게도 본인이 만든 컨트롤의 사용법을 몰라 다른 사람이나 자기가 만든 이전 코드를 찾아 봐야 합니다.

 

이처럼 문서화가 절실한 이유는 너무나 많습니다.

그러면 왜 개발자들은 자기 자신을 위해서도, 옆에 있는 동료를 위해서도 문서를 만들지 않는 것일까요.

 

글쓰기를 싫어하는 개발자

 

가장 큰 원인은 개발자들이 글쓰기를 정말이지 싫어한다는 점입니다.

많은 개발자가 명세서를 회피하는 이유는 글 쓰는 일을 워낙 싫어하기 때문이라고 생각합니다.

텅 빈 화면에서 명세서 작업을 시작한다고 생각하면 대략 난감할 뿐입니다. 개인적인 경험을 말하자면, 저는 글쓰기에 대한 공포심을 한 주에 세 페이지에서 다섯 페이지 분량으로 수필을 써야 하는 대학 강의를 들으면서 극복했습니다. 글쓰기는 근육과 같습니다. 더 많이 쓸수록 더 잘 쓸 수 있게 됩니다. 명세서 작업은 하고 싶은데 글을 잘 못쓴다면 간단한 일기를 쓰고, 블로그도 만들어 보고 , 창조적인 쓰기 수업을 수강하고, 4년 동안 티격태격 싸워왔던 대학동기나 룸메이트에게 보내는 멋진 편지를 써보세요.”

조엘 온 소프트웨어 67P

 

저도 사실 글 쓰는 게 쉽지가 않습니다.  짧은 글 하나 적는데도 상당히 많은 시간이 걸리고, 간만에 글 하나 적어 보려면 하루 종일 쓰고 지우기를 반복하기 일쑤였습니다.

하지만, 조엘 스폴스키가 적은 것처럼 글쓰기가 습관처럼 몸에 베이도록 계속해서 노력하니 조금씩 나아지더군요.

개발자라면.

-       본인이 만든 라이브러리에 대한 간단한 사용법과 샘플 정도는 만들 수 있어야 합니다. 형식에 구애 받을 필요는 없습니다. 누군가에 의해 강제된 형식에 의해 문서를 만들다 보면, 문서 만들기 자체가 형식으로 치우칠 수 있습니다. 본인이 생각하기에 나를 비롯한 다른 개발자들이 서로 충분히 알아 들을 수 있는 내용으로 문서를 채워나가면 그뿐이라고 생각합니다.

-       회의 자료부터 문서를 만들어 보면 어떨까요?. 회의자료를 제대로 작성하려면 회의내용이 집중해야 하고, 다시 한번 회의내용을 검토하면서 빠진 부분을 생각해 볼 수 있고, 회의의 결과에 대해 본인이 추후 개발을 하게 된다면 분명한 이해를 바탕으로 개발할 수 있게 됩니다.

-       게시판이나 WIKI, 스프링 같은 팀 내 개발자간 문서를 공유할 수 있는 곳이 있어야 합니다. 각종 개발 팁과 개발 자료, 회의 문서를 올려두고 서로 공유할 수 있는 곳이 있어야 합니다.

 

개발자의 문서화를 가로 막는 가장 큰 벽, 지속적인 문서 업데이트

 

문서를 만들고 나면 다음 문제가 있습니다.

프로그램은 계속적으로 수정이 되어 개선되는데 반해 문서로 Follow up 해서 같이 수정해 줄 수 있느냐 하는 문제 입니다.

누군가, 가장 좋은 문서는 프로그램 그 자체라고, 코딩을 자동으로 문서화하는 게 가장 좋다고 얘기하는 사람도 있지만 저는 반대입니다.

클래스 라이브러리의 전체 그림을 코드를 보고 파악한다는 것은 정말이지 엄청난 시간낭비입니다. 그 라이브러리를 사용하는 사람들이 꼭 알아야 하는 내용만 문서에 나와 있으면 되고, 문서에 그림등이 첨부 되어 있다면 한눈에 이해할 수 있어 개발 시간을 획기적으로 줄일 수 있기 때문에, 아직까지는 가장 좋은 문서화는 사람이 손으로 만드는 방법이 최고라고 생각합니다.

 

일부 프로그래밍 팀은 폭포수사고방식으로 무장하고 있습니다. 대부분 사람들은 모든 프로그램을 한번에 설계 하고 명세를 적어 출력해서 옆 방에 있는 프로그래머에게 집어 던진 다음에 집으로 갑니다. 제가 할 말은 하하하하하하하!” 뿐이랍니다.

이런 접근방식 때문에 명세에 대한 평판이 나빠집니다. 많은 사람들이 저에게 명세는 쓸모 없는 거야. 왜냐하면 아무도 명세에 따라 행동하지 않으며, 명세는 언제 읽어봐도 낡고 쓸모 없으며, 결코 제품을 반영하지 않기 때문이지.” 라고 말합니다.

잠시만 기다리세요. 낡고 제품과 동떨어진 명세는 당신네 회사 명세입니다. 우리 회사 명세는 주기적으로 개정하기에 현실을 반영합니다. 즉 제품을 개발하고 새로운 결정사항이 내려지면 계속 업데이트를 합니다. 명세는 항상 제품이 동작하는 원리를 최대한 반영하는 그림자입니다. 명세는 단지 제품이 코드 완료시점(다시 말해 모든 기능이 완벽하지만, 여전히 테스팅과 디버깅작업이 남아 있는 상황)에서 굳어질 따름입니다.

조엘 온 소프트웨어 81P

 

조엘 스폴스키의 회사처럼 제대로 문서를 업데이트할 수 있다면 얼마나 좋을까요.

하지만, 지속적인 문서 업데이트가 100% 보장 되지 않더라도 개발자를 위한 개발자에 의한 문서 작성은 꼭 필요합니다. 더불어 회사 차원에서 프로그램 개발시간 이외에 프로그램을 문서화할 수 있는 시간을 개발자에게 주어야 합니다. 개발시간에 쫓기다 보면, 문서에 대한 중요성을 사실 그다지 윗사람들은 중요하게 생각하지 않습니다. 다른 개발할 게 얼마나 많은데 이미 만들어진 코드를 문서화하는데 시간을 보내고 있느냐라고 얘기하는 상사가 있다면 --;; 할 말 없습니다. 땟치 해 주세요 ^^

 

혹시. 개발자가 좀 더 자연스럽게 문서를 만들게 하고 만들어진 문서를 잘 공유하면서, 주기적인 문서 업데이트를 체계화할 수 있는 좋은 경험을 나누어주실 분 계신가요?

 
  • BlogIcon 김제준 2007.07.22 14:24 신고

    잘 읽고 가요.
    저도. 글쓰기 연습을 많이 할려고 노력중이랍니다.
    되도록 명세서 작성을 자세히 할려고 해요. ^^;

    • BlogIcon esstory 2007.07.22 14:39 신고

      글쓰기중 특히 명세서 만드는 부분은 쉽지가 않더군요.
      혹시 좋은 노하우가 있으시면 같이 공유해 주세요
      댓글 감사합니다 :)

  • BlogIcon 오버탑 2007.07.25 14:06

    맞스니다. 에이전스와 같은 회사는 잘 되는데
    일반 컨텐츠 회사의 개발자들은 관리가 어렵더구욘
    저또 한 그럽습니다. 다시금 만들어서
    관리를 해야겠네여

    • BlogIcon esstory 2007.07.25 14:11 신고

      저자신도 문서작업은 계속 미루면서 게을리 하게 되는 문제가 있더군요. 하루종일 한가지 생각만으로 몰두하게 되는 개발자들은 더욱 힘든건 사실일거 같습니다.

      블로그를 하면서 참 다양한 개발자분들을 만나게 되는거 같아 반갑네요.

      리플 감사합니다. ^^;

  • 2008.03.24 12:13

    비밀댓글입니다

  • noname 2008.09.28 18:04

    1년 전의 이런 고민과 과정 후 요즘은 문서화에 어떤 변화가 있었는지 궁금합니다. 이제 국내에 그럭저럭 쓸만한 스프링노트같은 위키 기반 문서화 툴도 생겨났고, 필요성을 느낀 사람들이 나름대로 자신만의 방법을 찾지 않았을까 싶은데요.

    esstory님은 어떠한 방법으로 저러한 위기(?)를 극복하고 계신지 알고 싶습니다. 기회가 되면 최근의 문서화 방법이나 거쳐갔던 과정을 소개해주시면 좋겠습니다. ^^

  • 나비 2009.05.12 16:25

    퍼가서 두고두고 읽을께요 좋은글 감사합니다 그리고 인터페이스 관련글도 정말 감사합니다 (__)(--)(__)(--)