소프트웨어 문서화
IT위키
더 많은 작업
소프트웨어 문서화(Software Documentation)는 소프트웨어를 개발·운영하는 동안 요구사항, 설계, 코드, 시험, 사용법 같은 정보를 정해진 형식의 문서로 남기는 활동과 그 결과물이다.
소프트웨어는 눈에 보이지 않는 논리의 집합이라 만든 사람의 머릿속에만 있으면 다른 사람이 이해하거나 고칠 수 없다. 문서화는 개발 단계마다 무엇을 왜 그렇게 만들었는지를 기록해, 개발자 사이의 의사소통과 이후의 유지보수를 가능하게 한다. 참고 문서가 없고 만든 사람도 없어 고치기 어려운 코드를 외계인 코드라 부르는데, 문서화가 그 대책이다.
| 단계 | 대표 문서 |
|---|---|
| 요구 분석 | 소프트웨어 요구사항 명세서(SRS), 유스케이스 명세 |
| 설계 | 아키텍처 설계서, 데이터베이스 설계서, 화면·인터페이스 설계서 |
| 구현 | 소스 코드 주석, 프로그램 명세서, API 문서 |
| 시험 | 시험 계획서, 시험 케이스, 시험 결과서(IEEE 829) |
| 운영·유지보수 | 사용자 설명서, 운영자 설명서, 변경 이력·형상 관리 기록 |
문서의 양식과 작성 규칙을 표준으로 정해 두면 누가 써도 같은 구조가 나온다. 개발자가 얻는 이득은 다음과 같다.
- 분석과 설계가 쉬워진다. 무엇을 적어야 하는지가 정해져 있어 빠뜨리는 항목이 줄고, 앞 단계 문서를 다음 단계의 입력으로 그대로 쓸 수 있다
- 유지보수가 쉬워진다. 원래 개발자가 없어도 문서로 구조와 의도를 파악해 고칠 수 있다
- 확장성이 생긴다. 기능을 덧붙일 때 영향을 받는 부분을 문서에서 찾을 수 있다
- 개발자·관리자·고객 사이의 의사소통이 정확해지고, 인수인계와 감리·검사의 근거가 된다
- 품질 보증과 재사용의 바탕이 된다
프로그램 개발 인력이 줄어드는 것은 문서 표준화의 이점이 아니다. 문서를 쓰고 검토하는 일이 늘기 때문에 개발 인력이 직접 줄지는 않는다. 이점은 이해·수정이 쉬워지는 데서 오는 품질과 유지보수 비용의 절감이다.
- 정확성 - 실제 소프트웨어와 내용이 맞아야 한다. 코드를 고치면 문서도 같이 고친다
- 일관성 - 같은 용어와 형식을 쓴다
- 추적성 - 요구사항에서 설계·코드·시험까지 서로 연결된다
- 최신성 - 형상 관리로 버전을 관리한다