와이즈스톤 와이즈스톤

기술인사이트

기술리포트

기술문서, 어떻게 해야 '잘' 쓰는 걸까? : 기술문서 작성 가이드
  • 작성자
    와이즈스톤 최수혁 책임연구원
  • 작성일
    2023-08-11
<목차>
1. 개요
2. 기술문서 작성 절차
3. 기술문서 작성 4원칙
4. 끝맺음
________________________________________

1. 개요

기술문서는 기술적인 정보를 비즈니스 환경에서 전달하는 중요한 요소입니다. 이는 기업 간의 커뮤니케이션과 협업을 위해 필수적인 도구로 사용됩니다. 이 블로그에서는 기술문서 작성의 중요성과 효과적인 작성 방법에 대해 이야기하고자 합니다.

1.1 기술문서 정의
비즈니스 간(Business-to-Business) 기술적인 정보를 전달하기 위해 사용되는 문서 작성 스타일입니다. 이는 기술 제품, 솔루션, 서비스에 대한 설명서, 사용자 매뉴얼, 기술 문서, API 문서, 통합 가이드 등과 같은 다양한 형태로 나타날 수 있습니다.

1.2 기술문서의 중요성
기술문서는 비즈니스 환경에서 기술적인 내용을 이해하기 쉽고 명확하게 전달하여 고객이 제품을 효과적으로 사용하고 문제를 해결할 수 있도록 도와줍니다. 이는 기술적인 용어와 개념을 비전문가에게도 이해할 수 있는 방식으로 설명하고, 제품의 가치와 이점을 강조하여 비즈니스 관점에서 설득력을 가집니다.
기술문서 작성은 기술적인 정보를 명확하고 효과적으로 전달함으로써 제품의 성공적인 도입과 사용을 지원합니다.

1.3 기술문서의 국내외 트렌드
<기술문서의 국내외 트렌드>

국외에서는 중요하게 여겨지고 있지만, 국내에서는 현재까지 중요도가 부족합니다.
기술문서의 국내외 트렌드는 5가지로 구분될 수 있으며 아래와 같습니다.

1.3.1 기술 문서의 중요성 인지
1.3.2 기술 문서의 실제 현업 활용성 – IT 업계에는 해당 항목이 가장 중요합니다.
1.3.3 기술 문서 간의 연관성
1.3.4 기술 문서 품질(정확성, 명확성, 일관성, 간결성)
1.3.5 기술문서 작성 교육


1.4 기술문서의 개념

작성자, 특정 독자의 구분을 해야 합니다.
1.4.1 작성자 : 개발자, 품질엔지니어, UI 설계자, 상품기획자, 테크니컬 커뮤니티케이터
1.4.2 특정 독자 : 기술 지식수준이 초급부터 고급까지인 개발자, 테스터, UI 설계자, 상품 기획자
※ 기술문서 작성 시 특정 독자에 따라 작성방법 및 내용이 달라지기 때문에 특정 독자 구분은 매우 중요합니다.

1.5 소프트웨어 분야의 기술 문서 종류

1.5.1 사용자 및 관리자 매뉴얼
1.5.2 소프트웨어 설치 가이드
1.5.3 소프트웨어 개발 키트(SDK) 가이드
1.5.4 애플리케이션 프로그래밍 인터페이스(API) 가이드
1.5.5 문제 해결 가이드 등
※ 품질 좋은 기술 문서란?
- 내가 잘 만들었다고 생각하는 것이 품질 좋은 기술 문서가 아닙니다.
- 특정 독자를 만족시키는 것이 바로 품질 좋은 기술 문서입니다.
- 품질 좋은 기술 문서를 제작하기 위해서는 기술문서 작성 이론, 국제 표준, 기술 문서의 사용성 테스트를 고려해야 합니다.


2. 기술문서 작성 절차


<기술문서 작성 절차>

2.1 계획(Plan)
2.1.1 제목(Title) 선정
주제와 목적이 분명하게 드러나야 합니다. 와이즈스톤이 개발한 이슈 트래킹 시스템인 'OWL ITS(아울 아이티에스)' 가이드를 예로 들어보겠습니다. 하기 그림과 같이 ‘OWL ITS’은 주제가 될 것이고, ‘사용법’은 목적이 될 것입니다.

<제목(Title) 예시>

2.1.2 특정 독자(사용자) 분석하기
-특정 독자 종류
⦁ 1차적 독자 : 기술 문서를 직접 사용하는 사람
⦁ 2차적 독자 : 기술 문서를 참고하는 사람(프로젝트에 직접 참여하지 않지만 간접적으로 관련이 있는 사람) 예) 상급자, 결제자
- 특정 독자의 분석 항목
⦁ 해당 프로젝트에 대한 사전 지식과 기술 수준
⦁ 주요 관심 항목
- 특정 독자 분석 방법
⦁ 타사의 기술 문서 작성 수준 조사
⦁ 특정 독자의 기술 지식에 대한 설문조사 (내부 문서 작성 시 활용)

- 특정 독자의 기술 지식수준별 기술 문서 작성 방법
⦁ 기술 지식수준이 높은 특정 독자 : 문서로 분류(Advanced Technical Reports),
⦁ 기술 지식수준이 낮은 독자 : 문서로 분류(Tutorials)
⦁ 기술 지식수준이 높은 독자 + 기술적 지식수준이 낮은 독자

- 특정 독자 체크리스트
⦁ 누가 1차적 독자인가요? (예 : 사용자 매뉴얼 – 고객사 엔지니어)
⦁ 2차적 독자는 있나요? 있다면 누구인가요?
⦁ 특정 독자는 이 문서를 가지고 무엇을 할 것인가요?
(예 : 의사 결정, 제품 및 서비스 이용)
⦁ 특정 독자는 문서 내 작성될 주제에 대해서 어떤 점을 알고 있나요?
⦁ 특정 독자가 이 문서로부터 알고자 하는 것은 무엇인가요?

2.1.3 기술 문서의 작성 목적 분석하기
- 내가 작성하나 기술 문서를 가지고 특정 독자가 무엇을 할 것인지 분석합니다.
⦁ 소프트웨어를 개발하기 위해 기술 문서가 필요한 것인가요?
⦁ 소프트웨어를 사용하기 위해 기술 문서가 필요한 것인가요?
- 기술 문서의 작성 목적에 따라 문서 종류와 내용 및 작성 방법이 달라집니다.
⦁ 소프트웨어를 개발하기 위해 기술 문서가 필요하다면 -> SDK 가이드, API 가이드
⦁ 소프트웨어를 사용하기 위해 기술 문서가 필요하다면 -> 사용자 및 관리자 매뉴얼

2.2 구조화
2.2.1 기술 문서의 목차(아웃라인) 작성하기
- 효과적인 목차 구성을 위한 가이드라인

2.2.2 목차 작성 이유 및 목차 수준
- 목차를 작성하는 이유 : 초안(Draft) 작성에 앞서 아이디어 구성을 위한 가장 일반적이고 효과적인 방법입니다.
- 기술 문서를 각각의 주제로 분리함으로써 어떻게 구성해야 할지 결정할 수 있습니다.
- 목차는 3수준(대제목, 중제목, 소제목)까지만 구성합니다.
단, 필요시 4수준까지 구성할 수 있습니다.
※ 서두 / 본문 / 말미 중에 가장 중요한 부분은 본문입니다. 본문은 특정 독자에게 하고 싶은 중심 부분입니다.

2.2.3 구성의 개요
- 구성은 기술 문서의 특정 독자가 필요한 내용을 빠르게 찾고 이해하기 쉽도록 각각의 내용이 논리적으로 연결된 것을 의미합니다.
- 구성은 두 개 이상의 주제 및 각 주제의 내용을 논리적으로 배열할 수 있습니다.
- 기술 문서를 작성하는 데 있어 구성이 가장 중요한 이유는 아래와 같습니다.
⦁ 구성은 특정 독자가 필요로 하는 내용을 쉽게 찾을 수 있게 합니다.
⦁ 구성은 기술 문서 작성자가 내용을 효율적으로 관리할 수 있게 합니다.

※ 좋은 구성이란?
- 독자가 원하는 내용을 쉽게 찾을 수 있도록 합니다.
- 내용을 쉽게 변경하거나 재사용 할 수 있도록 합니다.
⦁ 각각의 동작에 대해 별개의 주제로 정보를 구성할 경우, 기술 문서 작성자는 원하는 동작을 쉽게 추가, 삭제, 재사용 할 수 있습니다.

2.3 초안 작성
2.3.1 초안은 목차에 내용을 작성하는 것입니다.
- 중요 아이디어를 먼저 작성합니다.
- 초안을 작성할 때는 내용을 수정하면서 작성하지 않습니다. 그 이유는 내용을 작성하는데 집중하지 못하여 중요 아이디어를 잊어버릴 수 있기 때문입니다.
- 기술 문서 작성자가 가장 자신 있고 작성하기 쉬운 항목을 먼저 작성합니다.

2.3.2 기술 정보 종류
- 프로시저
⦁ 도입부를 반드시 작성합니다.
⦁ 누가 이 동작을 수행해야 하나요?
⦁ 왜 이 동작을 수행해야 하나요?
⦁ 언제 이 동작을 수행해야 하나요?
⦁ 특정 독자가 고려해야 할 사항이 있나요?
⦁ 특정 독자가 이 동작을 수행하기 전 반드시 수행해야 할 동작이 있나요?
⦁ 특정 독자가 동작을 완료하도록 지시 사항을 작성합니다.
⦁ 명령형으로 작성합니다.
⦁ 글머리 기호가 아닌 번호를 사용하여 동작을 순서대로 작성합니다.
⦁ 각각의 번호에 하나의 동작만 작성합니다.
⦁ 행동을 하는 주체가 누구인지 명확하게 작성합니다.

<프로시저 예시>

- 프로세스
⦁ 어떤 일이 어떻게 발생되는지 작성합니다.
⦁ 설명형으로 작성합니다.
⦁ 표, 목록 또는 다이어그램을 사용합니다.
⦁ ‘누가’, ‘무엇을’. ‘언제’, ‘어디에’에 해당하는 것을 설명합니다.
⦁ 어떤 일이 발생한 순서대로 설명하고 그 결과를 작성합니다.
⦁ 어떤 일이 발생한 하나의 단계가 다른 단계의 결과라면, 그 두 단계 간의 인과 관계를 설명합니다.

2.3.3 개념
- 문장 개념 : 카테고리, 특징
- 확장된 개념 : 기본적인 기능, 동작 원리, 사용 목적, 강점, 제약 사항

2.3.4 분류
- 각 항목을 공통되는 성질에 따라 종류별로 나눕니다.
- 표, 목록, 다이어그램을 사용합니다.

2.3.5 구조
- 각 항목의 전체가 어떻게 구성되어 있는지를 보여줍니다.
- 각 파트의 전체적인 관계를 보여줍니다.

※ 특정 독자 위주로 기술 정보를 작성하기 위한 가이드라인
- 목차 항목은 기술 문서를 처음 보는 특정 독자가 원하는 기술 정보의 섹션으로 바로 가기 위한 최소 정보가 어디까지인지를 고려하여 작성합니다.
- 특정 독자가 반드시 필요로 하는 내용만 작성하고 부가적인 내용은 가급적 지양합니다.
- 참고와 문장 안의 소괄호()는 가급적 사용하지 않습니다.
- 주석은 사용하지 않고, 필요한 내용은 본문에 작성합니다.
- 작성자가 이해하기 쉬운 것이 아니라 특정 독자가 이해하기 쉽도록 내용을 작성합니다.
- 목차는 3수준까지 (예. 1, 1.1, 1.1.1)만 작성합니다. 단, 필요시 4수준까지 작성할 수 있습니다.
- 글 없이 그림이나 표만 작성하지 않습니다. 글은 그림과 표를 구체적으로 설명합니다.
- 육하원칙에 맞춰 내용을 작성합니다. 특히 주어를 반드시 작성합니다.
단, 맥락상 주어가 없어도 특정 독자가 충분히 이해할 수 있는 경우에는 주어를 작성하지 않습니다.
- 약어 및 용어를 작성합니다.
단, 일반적으로 통용되는 용어 및 약어는 작성하지 않습니다.

2.4 수정 및 검토
2.4.1 처음 분석한 특정 독자가 바뀌지 않았는지 확인합니다.

2.4.2 특정 독자에 관점에서 문서를 검토합니다.

2.4.3 목차의 구성과 내용을 검토합니다.
- 특정 독자가 필요한 내용을 쉽게 찾을 수 있게 목차가 효과적으로 구성되어 있나요?
- 특정 독자가 내용을 한 번에 이해할 수 있게 단락이 명확하게 구성되었나요?
- 문장이 명확하게 표현되었나요?
- 모든 중요 항목에 대해 적절한 예제나 내용이 작성되었나요?
- 특정 독자가 필요로 하는 중요한 정보가 누락되지는 않았나요?
- 스타일 가이드(정확성, 명확성, 간결성, 일관성)를 준수했나요?

2.4.4 검토 가이드
- 맑은 머리와 좋은 컨디션을 유지해야 합니다.
- 포맷 : 문서 종류에 따라 적절한 포맷이 사용되었나요?
- 스타일 : 단어 선택, 문장 길이, 톤, 글꼴, 글자 크기, 문법이 스타일(작성) 가이드에 맞게 작성했나요?
- 한 번에 하나의 스타일만 검토합니다.
- 오탈자 유무와 구두점이 틀린 곳이 없는지 확인합니다.
- 주변 동료에게 검토 요청을 보내고 이해 못 하는 부분을 편집합니다


3. 기술문서 작성 4원칙


<기술문서 작성 4원칙>

3.1 정확성


3.2 명확성


3.3 간결성


3.4 일관성



4. 끝맺음

비즈니스 성공을 위한 기술적인 정보의 전달은 계속해서 중요성을 갖고 있으며, 지속적인 학습과 발전이 필요합니다. 이 블로그를 통해 기술문서에 대한 이해와 작성에 도움이 되었기를 바랍니다.