인수인계문서작성에 관하여

문서를 제대로 작성해서 제출해본 기억이 없어서... :twisted:

원래 문서는 다음 사람이 받아서 무리없이 일을 계속 진행해 나갈 수 있는 정도까지
작성하는게 맞을겁니다.
문제는 인계를 받는 사람이 어떤 사람인지를 모를때인데...
한번은 대기업에서 작성한 문서를 본적이 있었죠.
당시에는 C로 프로그램을 작성했었던지라 라인단위는 아니더라도 함수단위로 설명을
자세하게 써놓았더군요.
물론 각 변수에 대한 설명과 받는 인수 보내는 인수, 내부에서 사용하는 인수들의
설명까지 자세하게 적어놓고...
만일 조금 복잡한 알고리즘을 사용한 부분이라면 바로 그 라인위에 자세하게 설명을
덧붙여서 설명을 써놓았더군요.

가끔 외국과 우리나라에서 공개로 개발되고 있는 소스를 볼 때면 느끼는거지만 우리나라
개발자들은 주석에 큰 비중을 두지는 않는다는 생각이 듭니다.
즉, 자신이 이해했으니까 괜찮다는 생각에서인지 주석붙이는 작업을 잘 안하더군요.
결국 프로젝트 마지막에 문서작성하면서 머리쥐어뜯으면서 고생을 하죠.
몰아서 한다는건 상당히 귀찮은 일이잖아요? :)

만일 시간이 넉넉하다면 라인단위로 주석을 붙여보세요.
다시한번 소스를 자신의 것으로 만들 시간이라고 생각한다면 조금은 덜 지루해지지
않을까 생각되네요.

소프트웨어는 대체로 해당 프로그램을 손볼 수준(?)의 사람을 대상으로 인수인계문서를 만드는게 타당합니다. 즉, 프로그래머 수준이겠지요. 프로그래머도 여러
레벨이 있겠지만, 해당 프로그램을 접해서 무리없을 프로그래머를 대상으로 하는게
맞다고 생각합니다.
일반 프로그래머가 접하기 어려운 특정한(?) 분야라면, 이를 위한 레퍼런스를
언급해 주는것도 좋겠군요.

하하, 무슨 책쓰는 것도 아니고, 심하군요. 시간과 여력이 되신다면 해두면 좋겠지만,
제 경험으로 볼때 문서 만들어서 남겨도, 제대로 보는 사람도 없는 경우가 많더군요.

제 개인적인 생각으로, 인수인계는 역시 어깨너머로 넘기기가 가장 빠르고,
정확한듯합니다.

대충 작성과정을 "한편의 편지"로 남기시면 Ok되던데요.

만약 다른 문서화가 "거의"안되어 있다면?....

그땐 "지옥에 오신걸 환영합니다"라는 멘트뿐.. :twisted:

아래내용은 어디까지나 저희 팀에서 작성한 템플릿을 기준으로 하며
항목 가감은 가능하겠지요.
해당 프로그램중 부적당한 항목은 빼도 됩니다.

>>>프로그램 명세서의 경우 
-시스템 명: 보통 프로젝트 명
-요구사항 ID: R0001
-프로그램 ID:PG0002
-프로그램 명:xmlparser
-유형:batch
-용 도: xml parsing 한다...
-관련 라이브러리 명:comminlib.a 
-기본 디렉토리: /www/ddd
- Input/output: 인풋과 아웃풋 파일 형태
- 포트: 9999
- 서버방식: inetd daemon
- 통신 형식: TCP/IP
-주요 로직: 설명


>>>함수정의서
-함수 원형:int XXXX( char *jobfile, char *loadserver, int loadport, char *eqserver, int eqport, char *host, char *user, char *pass, char *alias, char *ctldir, int year, int month, int day, int hour, int min, int sec )
-파일명 : xxx.c
-설명:
-매개변수:
char *jobfile : 필요한 작업을 저장해둔 파일char *loadserver : loader가 있는 서버 IP 주소int loadport : loader가 있는 서버 Port 번호char *eqserver : 쿼리를 실행할 서버 IP 주소int eqport : 쿼리를 실행할 서버의 Port 번호char *host : Oracle DB 서버 IP 주소char *user : Oracle 접속 IDchar *pass : Oracle 접속 Passwordchar *alias : Oracle DB  aliaschar *ctldir : 모듈 해당 ctl 디렉토리 위치int year : 년int month : 월int day : 일int hour : 시int min : 분int sec : 초
-반환값:성공 : 0실패 : -1

문서정리가 잘 되어 있다면
나중에 유지보수하기도 쉽습니다.

도큐멘테이션도 신경써야 하는 데 너무 간과하지 않나 생각합니다.