문서쓰기

간만에 만난 친구가 일전에 개발회사에서 쓸데없는(!) 문서 쓰는 것에 대한 하소연을 들었다. 팀장으로서 오늘도 잡다한 문서를 작성하고 있는 본인에게 그런 불평을!!!!

다른 직종들의 경우 문서를 쓰는 것에 대해 당연하게 여기는 분야도 많으나 유독 프로그래머나 개발 관련 사람들의 경우 문서를 쓰는 것에 대해 불만이 많고 그 작업을 귀찮다고 여긴다. 그런 상황에서 생성되는 문서는 당연히 내용이 충분하지 못하고 별 도움이 안되며 그런 문서만 쓰고 보다보니 다시 그것을 만드는 작업에 대해 불필요하다고 느낀다. 덕분에 때로는 통신 포맷을 정리해 놓은 문서조차 제대로 기술이 되어 있지 않아서(있다 하더라도 예외나 확장등에 대해 정확히 기술되지 않아 정말 쓰레기정도의 문서만 존재하기도 한다) 전임자에게 욕을 한바가지 정도 해주고는 코드보고 정리하고는 메일 하나 보내고는 말아 버리기도 한다. 역시나 그 내용을 정리하는 작업은 불필요하고 귀찮다고 생각한다.

이런 문제의 가장 근본에는 대부분의 전산과정 학교/학원에서 글을 쓰는 법을 가르쳐 주지 않는다. 프로그래밍조차도 제대로 가르치지 않는 웃기지도 않는 대학들은 당연히 교수들에게 그런 개념조차 있을리 만무하고 상위권 대학에서 조차 다큐멘테이션에 대해 심도있는 지도를 하는 커리큘럼은 드물다. 프로그래밍 숙제에 대하여 레포트를 제출하긴 하지만 그 내용의 확인은 형식적이며 어떻게 쓰는 것이 좋은가에 대해서는 정식적인 수업이 없다. SE 수업에서 UML이 조금 등장할 지 모르겠으나 SE 자체가 전공선택인 경우가 많고 거기서 문서화는 챕터 하나의 비중도 되지 못한다. 전산/컴퓨터공학과라 딱지 붙은 곳에서는 1~2학년에 프로그래밍 언어를 배우는 동시에 문서쓰는 법을 같은 비중으로 배울 수 있도록 커리큘럼을 만들어야 하지 않나라는 생각이다.


이미 본인을 비롯하여 엉터리 전산과를 나온 사람들은 어떻게 해야 하는가... 별 수 없다. 대학을 상대로 손해배상 청구소송을 할 수 없다면 스스로 배울 수 밖에는 없다. 문서의 존재가치는 그것이 주는 정보성에 달려있다. 형식적으로 아무런 내용 없이 칸만 채우고 있는 문서는 차지하고 있는 몇 K의 하드 공간도 아깝다. 필요한 문서를 쓰고 정보를 담고 있어야 하며 개발 문서라 한다면 해당 부분에 대해 일을 진행하면서 생각한 모든 것들이 들어 있는 것이 좋다라 여긴다.

처음 쓰는 사람들은 어떻게 써야 하는지 막막할 때가 많다. 그렇다면 도움이 되는 것이 RUP등에서 제공하는 샘플을 참고하기 바란다. 시중의 많은 책들이나 인터넷에서 쉽게 샘플을 볼 수 있을 것이다. 잘 모를 때는 다른 사람의 것을 빼기는 것만한 방법이 없을 것이다. Steve McConnel 방식으로 Template를 사용하는 것도 좋은 방법이다. 미리 정해져 있는 문서내 단락구성에 빈칸 채우기 방식을 상당히 권장한다. 어느정도 익숙해 지면 Joel이 이야기 한 대로 정형적인 form을 걷어 치우고 필요한 부분만 기술을 할 수 있을 것이다.

본인은 사진이나 스캐닝도 가끔 이용한다. 최종적인 형태는 formal한 문서가 좋을 것이다. 생각이 정리되고 나면 깔끔하게 도표와 글로 정리가 될것이기 때문이다. 하지만 그 전까지는 A4 이면지에 그림을 그려보기도 하고 화이트 보드에 낙서를 하곤 그것을 사진으로 보관하는 편도 좋다.(휴대폰카로는 찍지 마라. 해상도가 아직 너무 낮다). 본인도 실수한 것이지만 이런 중간 기록들을 절대 없애지 마라. 모든 기록들이 정보이며 문서이다.


개발팀 소속에 있어, 우선 당신이 팀장이라면 절대 팀원들에게 형식적인 문서를 강요해서는 안된다. 하지만 문서 없이 일이 진행되지 않도록 해야 한다. 팀원이라면 문서 작업을 절대 등한시 하지 마라. 코드 한줄을 어떻게 이쁘게 작성하느냐 고민하는 것과 마찬가지로 그 코드가 어떻게 튀어 나왔는지 기술하는 것도 상당히 중요하다. 프로그램 코드는 한가지 산출물에 불과하고 사용자 매뉴얼과 더불어 프로그래의 메뉴얼도 상당히 중요한 산출물임을 생각해야 한다. 제품 출시가 된다는 것은 여러가지 산출물들이 모두 완성된다는 것이고 거기에는 제품뿐만이 아니라 메뉴얼과 문서들도 포함되어야 한다는 마인드가 필요하다.

~~~~~~~~~~~

그러고 보면 문서화의 가장 큰 적은 제품 듀에 코드만 완성되면 된다는 영업과 대가리(--;)들이 문제가 아닐까 한다. 심지어 버그가 좀 많이 있어도 자신들이 몸으로 막겠다 하는...