4. 테크니컬 문서 작성방법 - 문경숙

1. 테크니컬 문서 개념과 종류

가) 테크니컬 문서의 정의

• 참조 문서의 기술 또는 제품의 취급방법, 기능 및 아키텍쳐 개발/사용 등을 기록한 문서
• 최종 사용자, 관리자, 서비스, 유지보수 기술자 등이 제품의 내, 외부를 이해할 수 있도록 충분한 정보를 제공하는 문서
• 엔지니어링, 기술, 과학 등 전문 분야의 의사소통 방식에 따라 전문 용어를 많이 사용하여 작성하는 문서
• 기술문서: 특정 사실에 대해 설명하거나 상대방을 설득 또는 어떤 행동을 지시하는 등의 내용 포함
• 비즈니스, 산업, 전문영역에 상관없이 업무 수행을 위한 모든 글쓰기와 의사소통

나) 테크니컬 문서의 특징
① 명확성
추상적, 윤유적 수사법 혼란 유발, 사용지양

② 정확성
자료, 데이터 바탕 객관적인 사실에 부합하도록 정확한 내용으로 작성
합리적 사고 바탕 정확, 일관성 유지

③ 체계성
짜임새있게 구성, 전체적으로 통일성 필요

다) 테크니컬 문서의 종류

구분	기술문서의 종류	설명
프로젝트 관리 기술문서	사업계획서	사업진행전, 사업타당성 검토, 미래 위험 미리 대비, 사업 내용, 사업대상 시장 특정, 성공가능성 등 사업 관련 내용 포함 지침서
	정보제공요청서	외부 업체에 대한 간략한 소개, 신용정보, 용역 수행경험, 프로젝트 예산 범위
	제안요청서	발주기관의 시스템, 업무현황, 문제점, 요구사항, 제안에 필요한 요구사항을 상세하게 기술한 문서,
	제안서	제안업체가 발주된 사업을 수주하기 위해, 업체의 경험과 능력 및 사업을 구체적으로 분석한 내용을 제출하는 문서, 발주업체는 제안서를 기반으로 업체 선정
	프로젝트 관리 계획서
	Requirement Traceability Matrix	사용자의 요구사항이 최종 인도물에 반영되기까지 과정을 추적하는 문서
	프로젝트 완료 보고서	프로젝트 목표 대비 실적과 프로젝트 교훈 그리고 후속 프로젝트 견적을 위한 통계항목 정리사항 등을 포함하여 프로젝트 수행결과를 요약하고 사용자에게 프로젝트 완료를 확인하는 문서
프로젝트 개발 기술 문서	분석서	SW 제품을 설계하거나 제조할 시 필요한 세부적인 요건사항들을 명시한 문서
	설계서	SW 제품을 설계하거나 제조할 시 필요한 세부적인 요건사항들을 명시한 분석서를 바탕으로 기술된 요구사항들을 구현하는 문서
	개발문서
	테스트 문서	테스트 대상과 테스트 케이스, 테스트 데이터를 정의하여 테스트 시에 활용하도록 작성한 문서
	설명서	제품에 대해서 알지 못하는 고객 등을 대상으로 제품의 이치나 현상, 지식이나 정보 등을 알기 쉽게 풀이하여 독자가 그 대상을 정확하고 쉽게 이해할 수 있도록 작성한 문서

2. 테크니컬 문서 작성의 원칙과 방법

가) 테크니컬 문서 작성 시 표현 및 서술방식

구분	항목부호
1수준	I, II, III, IV, V, VI
2수준	1,2,3,4,5
3수준	1)2)3)4)5)
4수준	(1)(2)(3)(4)(5)
5수준	①②③④⑤⑥⑦⑧⑨⑩

[자주 틀리는 외래어 표기법 사례]

원문	틀림	맞음
Application	어플리케이션	애플리케이션
Accessory	악세서리	액세서리
Business	비즈니스	비즈니스
Cache	캐쉬	캐시
Column	컬럼	칼럼
Contents	컨텐츠	콘텐츠
Control	콘트롤	컨트롤
Desktop	데스크탑	데스크톱
Drag and drop	드래그앤드드랍	드래그 앤드 드롭
Manual	매뉴얼	매뉴얼
Message	메시지	메시지
Network	네트웍	네트워크
Presentation	프리젠테이션	프레젠테이션
Shareware	쉐어웨어	셰어웨어

나) 테크니컬 문서 작성 시 유의사항
① 독자관점 이해되게, 쉽게,
② 독자가 다른 문서를 참조하지 않아도 이해할 수 있도록 작성, 의문사항이 생기거나 혼동을 주는 일이 없도록
③ 약속된 템플릿에 따라 작성

다) 명확한 테크니컬 문서 작성

항목	설명
연관성	문서의 주요 요구사항과 핵심 내용 간, 선정된 핵심 내용과 작성된 내용이 상호 연결되는 논리적 인과관계가 있어야 함
일관성	하나의 방법이나 관점 등이 처음부터 끝까지 한결같은 성질을 가져야 함, 문서에 기술되는 주요 내용의 표현이 비슷해야 함을 의미 예) 형식적으로 폰트, 색상, 화법이 일정해야 하고 내용적으로는 교통수단이라면 기차, 버스, 택시 등으로 배치되어야 함
정확성	SW 테크니컬 문서 작성 시에는 기본적으로 정확하게 작성하여야 함 기술되는 구조 및 알고리즘 등은 SW에 요구되는 기능을 정확하게 수행할 수 있도록 기술되어야 함
적합성	테크니컬 문서는 문서의 작성 목적에 맞도록 적합하게 기술되어야 함 기술 문서를 사용하는 사용자의 사용 목적에 맞도록 문서의 목적을 명확하게 기술하도록 함

3. 테크니컬 문서 작성

가) 사업계획서(기획서)

구분	내용
1.일반현황	사업을 위한 개략적인 내용
2. 목표	해당 사업을 통해 얻으려고 하는 목표를 기술
3. 내용	사업의 내용
4. 사업방법	사업을 수행하는 방법
5. 재무	추진 비용 추진 인력
5. 기대효과	사업을 통해 얻을 수 있는 기대효과

[사업계획서 작성 원칙]

구분	내용
이해하기 쉽게 작성	투자자, 고객 납득하게 제품 및 기술성 작성 단순, 보편 내용 구성
현실성 있게 작성	공공기관, 전문기관의 증빙자료를 근거로 작성
핵심내용 강조	제품의 특성 중심 제품 설명
일관성과 정확성	숫자, 단위 등을 통일 표현, 일관된 흐름과 주제를 가지고 작성
문제점 및 위험요인의 심층분석	잠재 문제점, 위험요소 분석, 지연, 불가능되지 않게 다각도 점검 요구

나) 정보제공 요청서(RFI: Request for Information)
외부 업체에 대한 간략한 소개, 신용정보, 용역 수행경험, 프로젝트 예산 범위

구분	내용
1. 사업개요	사업명, 추진 배경 및 목적, 사업 범위 RFI 제출 요령 등
2. 발주업체 정보	업무 현황(사업목표/추진방향 등), 정보화 현황, 개선사항 등
3. 주요 요구사항	비즈니스 및 기술적 요구사항, 구현, 교육, 프로젝트 관리, 프로젝트 예산 등

다) 제안요청서 (RFP: Request for proposal)
발주기관의 시스템, 업무현황, 문제점, 요구사항, 제안에 필요한 사항을 상세하게 기술한 문서, 발주기관이 필요로 하는 사항을 제안자가 명확하게 제안하도록 하는 공식문서

구분	설명
1. 사업의 개요	추진배경 및 필요성, 서비스 내용, 사업 범위, 기대효과
2. 현황 및 문제점	업무 현황, 정보화 현황, 문제점 및 개선방향
3. 사업 추진방향	추진 목표, 추진 전략, 추진 체계, 추진 일정
4. 제안 요청 내용	제안요청개요, 목표시스템 개요도, 개발대상업무 내역 및 구성요건, 도입대상장비 내역 및 구성요건, 초기 자료 구축요건, 표준화 요건, 시스템 운용조건, 교육지원 요건, 기술지원 요건, 유지보수 요건 등

라) 제안서
제안업체가 발주된 사업을 수주하기 위해, 업체의 경험과 능력 및 사업을 구체적으로 분석한 내용을 제출하는 문서, 발주업체는 제안서를 기반으로 업체 선정

구분	내용
1. 사업의 개요	제안의 배경, 목적, 범위, 전제조건, 기대효과 등
2. 제안업체 일반	일반현황, 조직 및 인원, 주요 사업 내용, 주요 사업 실적
3. 기술부문	시스템 구성도, 시스템 구축방안(시스템 사양 및 기능, 구성장치 내역 및 세부규격, 시스템 납품 및 설치방안 등), 소프트웨어 개발방안(개발방법론 활용방안, 업무 개발방안, 초기 데이터 구축 방안, 시스템 통합 방안 등) 등
4. 사업관리부문	품질보증계획, 위험관리계획, 추진일정계획, 업무보고 및 검토계획, 수행조직 및 업무분장, 투입인력 및 이력 사항 등
5. 지원 부문	교육 훈련계획, 유지보수계획, 기술이전계획, 기타지원사항
6. 기타	별첨: 가격산출근거서

마) Requirement Traceability Matrix
사용자의 요구사항이 최종 인도물에 반영되기까지 과정을 추적하는 문서, 사용자의 요구사항이 제품에 어떻게 반영되었는지 추적, 구현제품이 어떤 요구사항을 바탕으로 구현되었는지 역추적 가능, wbs, 설계, 개발된 제품, 테스트 시나리오 등을 사용자 요구사항과 매핑하여 관리

구분	내용
1. 사용자 요구사항	RFP 요구사항 및 수집된 요구사항
2. 분석 산출물	사용자 요구사항에 매핑되는 분석내용들 USECASE, 요구사항 분석서 등
3. 설계 산출물	사용자 요구사항과 매핑되는 설계 내용들 ARCHITECTURE 화면설계서 모듈설계서 인터페이스 설계서 DB 설계서
4. 구현 및 테스트 산출물	구현산출물 구현 기능 SOURCE MANUAL 테스트 산출물 통합시험 테스트 케이스 사용자 시험 테스트 케이스 시스템 시험 테스트 케이스

바) 분석서
SW 제품을 설계하거나 제조할 시 필요한 세부적인 요건사항들을 명시한 문서. SW를 개발하기 위해 SW에 대한 요구사항을 이해하기 위해 작성하는 문서. SW에 요구의 성격과 범위를 이해하고 제약사항들을 명확히 기술하는 문서. 설계참조사항, 구현SW전반적인 사항 포함

[분석서 구성(예시)]

구분	내용
1. 일반사항	정의 및 개요
2. 일반 기술사항	제품의 기능 사용자 특성 가정 및 의존사항
3. 상세내용	기능적 요구사항 입력물 프로세싱 산출물 수행 요구사항 디자인 제약사항 외부 인터페이스 요구사항 사용자 인터페이스 하드웨어 인터페이스 소프트웨어 인터페이스

[분석서 작성 원칙]

구분	내용
명확성	시스템이 수행할 모든 기능과 시스템에 영향을 미치는 제약 조건을 명확하게 기술
간결성	명세 내용은 고객과 개발자 사이에서 모두가 이해하기 쉽고 간결하게 작성
검증가능성	기술된 모든 요구사항은 검증이 가능하기 때문에 원하는 시스템의 품질, 상대적 중요도, 품질의 측정 및 검증 방법 및 기준 등을 명시
보편성	요구사항 명세서는 시스템의 외부 행위를 기술하는 것으로, 특정한 구조나 알고리즘을 사용하여 설계하지 않도록 함
변경용이성	참여자들이 시스템의 기능을 이해하거나, 변경에 대한 영향 분석 등을 위하여 계층적으로 구성
용이성	요구사항을 쉽게 참조할 수 있도록 고유의 식별자를 가지고 번호화하고, 모든 요구사항이 동등한 것이아니기 때문에 요구사항을 우선 순위화

사) 설계서
SW 제품을 설계하거나 제조할 시 필요한 세부적인 요건사항들을 명시한 분석서를 바탕으로 기술된 요구사항들을 구현하는 문서. SW를 이루는 구성 및 프로그램들의 관계를 파악하는 구조설계, 모듈들 혹은 시스템 간의 인터페이스 설계, 자료를 저장할 자료 저장소의 설계, 프로그램 알고리즘의 설계 및 사용자 인터페이스에 대한 설계 포함

구분	내용
1. 일반사항	정의 및 개요
2. 구조 설계	SW 구성품 SW 구성품들의 관계
3. 프로그램 설계	SW 구성품의 알고리즘 설계 SW 구성품의 INPUT, OUTPUT 설계
4. 인터페이스 설계	관련 SW 구성품 개요 SW 구성품 간의 인터페이스 내역
5. 자료 설계	자료 저장소 개요 자료 저장소 설계

아) 테스트 설계서
구현한 제품을 테스트하기 위해서는 테스트 대상을 정읳아고 테스트 시에 정상 결과와 예외 결과 등 결과값에 대해서 명확하게 이해하고 진행하여야 한다.
테스트 설계서는 테스트 대상과 테스트 케이스, 테스트 데이터를 정의하여 테스트 시에 활용하도록 작성한 문서이다.

구분	내용
1. 테스트 항목	테스트의 유형: 기능성, 성능, 사용성 등 테스트 ID: 테스트 항목을 유니크하게 정의 테스트 항목: 테스트되는 내용들을 정의
2. 테스트 케이스 및 데이터	테스트의 유형: 기능성, 성능, 사용성 등 테스트 ID: 테스트 항목을 유니크하게 정의 입력: 테스트를 위해 입력해야 될 내용과 데이터 예상출력: 테스트를 위해 입력된 내용에 따라 예상되는 결과값과 데이터

자) 설명서
새로운 제품(기술)을 잘 사용하려면, 사용자는 그 제품의 원리나 특징, 조작방법 등을 알아야 한다.
제품에 대해서 알지 못하는 고객 등을 대상으로 제품의 이치나 현상, 지식이나 정보 등을 알기 쉽게 풀이하여 독자가 그 대상을 정확하고 쉽게 이해할 수 있도록 작성한 문서

구분	내용
1. 일반사항	제품의 명칭, 제품 개요, 제품의 특성, 중요 기능의 장단점 등
2. 사용법 및 설치/점검사항	사용시 주의사항 설치시 주의사항 사용 및 설치 방법 점검 방법 등
3. 유지보수 및 문제 해결	관리방법, 문제점의 증상 및 해결 방법 등
4. 기타	색인, 보증서, AS 절차 등

차) 프로젝트 완료 보고서
프로젝트 목표 대비 실적과 프로젝트 교훈 그리고 후속 프로젝트 견적을 위한 통계항목 정리사항 등을 포함하여 프로젝트 수행결과를 요약하고 사용자에게 프로젝트 완료를 확인하는 문서

구분	내용
1. 프로젝트 결과요약 시스템 기능요약 프로젝트 이익평가 계획 대비 실적 프로젝트 만족도 평가 향후 지원 계획 후속 프로젝트 계획	시스템 기능, 전달 산출물 목록, 시스템 설치 현황등 정성ㅈ거, 정량적 평가 등 예산, 투입공수, 기간 등 요구사항 충족도, 사용자 평가 등 유지보수, 고객 지원 방안 등 향후 계획
2. 프로젝트 교훈	교훈, 원인,문제점, 프로젝트 결과, 개선 방안 등
3. 프로젝트 통계	항목유형, 통계 항목, 예측치, 실적치 평가 등

4. 목적에 부합하는 테크니컬 문서 작성

작성 전문자, 과학자가 자신의 아이디어나 연구 성과 등을 독자에게 효과적으로 전달하는것
내요을 명확하고 효율적으로 전달, 문서작성에 투자하는 시간과 노력은 중요하고 가치 있는 일, 자신의 전문 분야의 연구, 성과 및 업적에 대한 효과적인 문서작성 스킬 필요

가) 테크니컬 문서 작성 핵심 체크리스트

구분	내용
독자에게 말하고자 하는 작성자의 핵심 내용은 무엇인가?	테크니컬 문서 작성 방향과 작성 내용에 대한 지침이 되는 대상 기술의 핵심 내용이 제공되어야 한다.
문서에서 다루는 기술의 특장점 및 차별화 요소는 무엇인가?	기존기술 또는 경쟁 기술 대비 본 기술의 장점을 부각하고 단점을 최소화하여 본 기술의 차별적 특장점이 잘 전달될 수 있도록 한다.
독자들에게 어떻게 효과적으로 전달할 것인가?	독자가 동일조건(예산, 요구사항, 일정 등) 하에서 기존 기술 또는 경쟁기술보다 더 나은 가치를 제시하였다고 평가하도록 표현한다.

나) 테크니컬 문서 점검을 위한 핵심 체크리스트

구분	내용
핵심 논리의 전개는 일관성이 있는가?	테크니컬 문서 작성 내용의 논리전개가 일관적인지 여부와 논리를 뒷받침하기 위한 사실, 근거가 잘 제시되었는지 확인한다.
작성된 문서의 내용은 이해하기 쉽고 직관적인가?	문서를 구성하는 문장의 길이가 적당하고 이해하기 쉽게 작성되었는지 여부를 확인한다.
적절한 사례와 예시, 수치와 도식이 제공되었는가?	독자가 이해하기 쉽고 오해가 없도록 적재적소에 사례와 그림, 표와 도식이 제공되었는지 확인한다.