시작하며
안녕하세요. 카카오엔터프라이즈 테크니컬라이팅 팀의 Crystal(김유리)과 Sandy(차신영)입니다.
이전 포스팅에서 목차의 중요성과 기술 문서 작성 5단계 등 테크니컬라이팅 기법을 설명드렸는데요. 오늘은 그 연장선으로 기술문서 본문 첫 페이지에 등장하는 개요에 대해 살펴보고, 개요의 역할과 작성 방법 등을 알아보겠습니다.
누군가를 처음 만날 때 듣게 되는 자기소개처럼 기술문서의 도입부에 위치한 ‘개요’는 해당 문서를 처음 펼쳐본 독자에게 전하는 문서의 자기소개라고 할 수 있습니다. 즉, 개요를 통해 독자는 해당 문서가 어떤 내용인지 대략적으로 파악할 수 있는데요. 훌륭한 1분의 자기소개가 면접의 당락을 가를 수 있듯이, 잘 정돈된 개요는 독자와 마주한 문서의 첫인상을 결정하는 동시에 해당 문서의 가치를 향상시킬 수 있습니다.
개요란 무엇인지, 왜 중요한지, 그리고 어떻게 하면 매력적인 개요를 작성할 수 있는지 지금부터 살펴보도록 하겠습니다.
▪ 개요란?
개요의 사전적 의미(출처: 국립국어원 표준국어대사전)는 "간결하게 추려 낸 주요 내용"입니다. 특히 글쓰기 준비 단계에서 전체적인 내용과 흐름을 구상하기 위해 작성하는 일종의 계획이라고 일컫기도 합니다. 다시 말해, 개요는 문서의 도입부에서 독자가 문서 전체를 읽을 수 있도록 준비시켜주는 단계라고 할 수 있을 것 같습니다. 물론 이 단계는 개요의 사전적 의미인 "간결하게 추려 낸 주요 내용"도 포함됩니다.
기술문서 이외의 다른 문서에도 개요가 존재하는데요. 짧은 이메일부터 아주 긴 논문까지 모든 종류의 문서가 시작되는 도입부를 개요라고 부를 수 있습니다. 그렇기 때문에 개요의 길이도 천차만별입니다. 이메일 같은 경우에는 한두 줄로 개요가 완성되는가 하면, 긴 설명문이나 기술문서의 경우에는 개요가 한 장을 거의 채우기도 합니다. 이렇게 다양한 모습을 가진 개요가 어떤 역할을 하는지 살펴보도록 하겠습니다.
▪ 개요의 역할
개요는 독자가 문서 전체를 읽기 전에 문서를 간략하게 소개해주는 역할을 하는데요. 그럼 개요의 역할을 구체적으로 살펴볼까요?
① 독자의 흥미 유발
첫 번째로 개요는 독자의 흥미를 유발합니다. 기술문서의 독자를 상상해보면 재미를 얻기 위해 문서를 읽지는 않을 텐데요. 독자는 어떤 서비스나 제품을 처음으로 사용하려 하거나, 사용 중에 막히는 부분 혹은 문제가 생겼을 때 기술문서를 열어보게 됩니다. 기술문서를 읽는 독자는 이 문서가 자신이 원하는 사용 방법이나 문제 해결 방법을 제공해주는지 파악하는 것이 가장 중요합니다. 개요를 읽고 "이 문서에는 내가 필요한 사용 방법이 포함되어 있구나"라는 생각이 들면 본문을 빨리 읽고 싶어지겠죠? 이처럼 개요는 독자의 관심을 끌고, 독자가 원하는 부분을 찾아 읽을 수 있는 동기를 유발해주는 중요한 역할을 합니다. 이런 동기 유발을 위해 이미지 자료나 동영상 자료를 활용하는 것도 좋은 방법이 될 수 있습니다.
② 본문의 요약
개요의 두 번째 역할은 본문의 내용을 요약하여 전달하는 것입니다. 앞서 말씀드렸듯이 대부분의 독자들은 개요를 읽은 후, 본문을 읽을지 말지 결정합니다. 그러므로 개요에서는 문서 전체를 읽지 않고서도 본문이 어떤 내용을 상세히 다루고 있는지 독자에게 대략적으로 알려주어야 합니다. 만약 개요에 원하는 내용이 없다면 독자는 더 이상 본문을 읽을 필요성을 느끼지 못하게 됩니다. 따라서 개요는 문서 전체의 내용을 간략히 설명한 후, 구체적인 내용을 본문에서 설명해야 합니다. 이를 위해서는 개요에서 문서의 주제를 명시하고 해당 내용이 어떤 방식으로 구성되어 있는지를 포함해야 합니다.
SDK 가이드를 예로 들자면, 해당 문서가 SDK를 활용하여 개발자가 원하는 기능을 만들 수 있는 가이드라는 점을 먼저 명시해야 합니다. 그리고 본문에서 자세히 설명될 SDK의 구성요소는 어떤 것이 있는지, 해당 구성요소들을 활용하여 어떻게 SDK의 기능을 적용하는지 그 흐름을 요약해서 포함할 수 있을 것입니다. 이를 통해 독자는 해당 문서가 본인이 필요한 내용이 들어 있는 문서인지를 알 수 있게 됩니다. 만약 문서에서 다루고 있는 SDK의 구성요소 중 하나에 궁금증이 있는 개발자라면 원하는 내용을 찾을 수 있게 될 것입니다.
③ 배경지식 전달
개요의 세 번째 역할은 독자가 문서를 이해하는데 필요한 배경지식을 전달하는 것입니다. 문서에서 핵심을 이루는 개념에 대한 정의를 제공하거나, 제품이나 서비스 개발에 관련된 히스토리 또는 배경 중 독자가 염두에 두어야 할 부분을 명시할 수 있습니다. 대부분의 기술문서에는 독자가 본문을 정독하기 전에 알아야 할 배경지식이 필요한 경우가 있습니다. 특히 기술문서는 제품이나 서비스를 처음 이용하는 사용자나 초보 개발자도 쉽게 읽고 따라할 수 있도록 지식을 쉽고 명료하게 전달하는 것이 중요한데요. 이를 위해 특정 기능이나 상품의 개발 배경을 설명하는 것도 좋은 방법입니다. “어떤 배경과 목적에서 이 기능을 왜 개발했을까?”라는 의문을 갖고 있는 독자들이 있을 수 있으므로, 이 기능을 왜 개발하게 되었고 어떠한 점을 개선했는지 등을 함께 기술하는 것도 독자 친화적인 개요라고 할 수 있습니다.
▪ 개요 작성 요령
실제 기술문서를 작성하다 보면 문서 본문보다 개요 작성이 더 어렵다는 분들이 꽤 있습니다. 개요는 본문의 요약이자 독자들에게 문서의 로드맵을 제공하는 중요한 역할을 하기 때문에 당연히 작성이 쉽지 않은데요. 다음의 개요 작성 요령을 숙지하면, 보다 쉽게 개요를 작성하실 수 있으실 것입니다.
① 개요는 본문 작성 후 작성하기
개요는 기술문서의 도입부에 존재하기 때문에 개요를 문서 작성 초기부터 작업하는 분들이 많으실 텐데요. 문서 작성 초기부터 개요를 작성하는 것보다는 목차를 구성하고 본문을 모두 완성하고 난 후, 제일 마지막 단계에서 개요를 작성하는 것이 좋습니다. 아무리 목차 구성이 제대로 되었다고 하더라도, 막상 본문을 작성하다보면 많은 변수가 발생하여 본문의 내용이 수정되기 마련인데요. 결국은 본문 수정에 따라 개요에 대한 내용도 반복적으로 수정하는 상황이 발생할 수 있습니다. 이렇게 계속해서 발생하는 수정에 따른 리소스 낭비를 줄이기 위해 목차 구성과 본문 작성이 완성된 이후 마지막 단계에서 개요를 작성하는 것을 추천합니다.
| 단계 | 상세 작업 |
| 목차 구성 | 해당 프로젝트의 기획 문서 또는 요구사항 명세서 등과 같은 자료를 수집하고, 관련 내용을 주제별로 그룹화하여 목차를 구성 (참고 : 목차의 중요성) |
| 본문 작성 | 주제별로 그룹화된 목차를 바탕으로 각 목차에 해당하는 대략적인 내용을 작성하고, 문서 본문을 작성 |
| 개요 작성 | 완성된 본문을 바탕으로 해당 문서를 요약하고, 독자가 본문을 읽기 전 알아야 하는 내용을 정리하여 작성 |
② 목적과 독자 정의하기
개요를 작성할 때 가장 중요한 것은 기술문서의 목적과 대상 독자를 명확히 정의하는 것입니다. 이 문서를 어떤 경우에 사용하는지, 어떤 정보를 제공하는지 등과 같은 문서의 목적을 명확히 해야 독자가 해당 문서를 적절한 상황에서 사용할 수 있습니다. 또한 해당 문서가 외부 또는 내부 개발자들을 대상으로 작성된 것인지, 어느 레벨의 개발자를 위한 것인지 등의 대상 독자를 명확하게 정의하는 것이 좋습니다. 내부 문서를 내부 개발자가 읽을 경우에는 이미 해당 기술에 대해서 잘 알고 있기에 약어 또는 내부 용어를 사용해도 문서를 이해하는데 문제가 없을 수 있습니다. 그러나 외부 개발자에게 같은 문서를 제공하면 해당 용어에 대한 정의를 알 수 없기에 문서를 이해하는데 어려움을 겪을 수 있습니다. 또한 개발자의 지식 수준에 따라서도 같은 문서를 이해하는데 차이가 있을 수 있는데요. 이런 혼란을 피하기 위해 개요에 문서의 목적과 독자 등을 정의하는 것이 좋습니다.
③ 큰 맥락에서 설명하기
기술문서는 일반적으로 특정 기술이나 기능 설명에 초점을 두고 작성됩니다. 기술이나 기능 등을 한 그루의 나무라고 보고 이 나무들이 모여 숲을 이룬다고 했을 때, 이 숲은 시스템이나 플랫폼이 됩니다. 따라서 해당 문서가 A 기능에 대해 설명한다고 해서 해당 기능만 설명하면 전체 시스템에서 A 기능이 어떻게 동작하고 어떤 역할을 하는지 간과하기 쉽습니다. 보통 작성자는 해당 기능이 전체적인 시스템 측면 또는 비즈니스 측면에서 가지는 중요성에 대하여 파악하고 있겠지만, 문서를 처음 읽는 독자는 이런 배경지식이 없다는 점을 이해할 필요가 있습니다.
따라서 특정 기능을 설명하는 문서라도 전체 시스템이나 큰 맥락에서 해당 기능이 어떻게 유기적으로 연관되어 있는지 설명하는 것이 좋습니다.
④ 목록으로 나열하기
개요는 기술문서를 읽는 독자와 첫 번째로 대면하게 되는 섹션으로 해당 기술문서의 로드맵 역할을 합니다. 독자에게 해당 문서의 로드맵을 줄 수 있는 가장 좋은 방법 중 하나는 본문에서 설명하고 있는 기능들의 목록을 테이블에 정리하고, 각 챕터의 링크를 연결하는 것입니다. 만약 본문에 10 개의 기능을 설명하고 있는 기술문서라면, 독자들은 대부분 이 기능들을 모두 사용하기보다는 자신들에게 필요한 몇 개의 기능을 선별해서 사용할 가능성이 큰데요. 모든 기능들이 한 곳에 정리된 목록 테이블에 각 연관 챕터를 링크로 연결해 둔다면 독자들은 원하는 챕터로 이동하여 필요한 정보를 파악할 수 있을 것입니다.
⑤ 시각 자료 활용하기
“그림 한 장이 천 개의 단어보다 낫다(A picture is worth a thousand words.)”라는 속담처럼 개요에도 독자의 이해를 돕기 위해 이미지 또는 테이블 등의 시각 자료를 활용하는 것도 좋습니다. 예를 들어 개발 구현 순서를 텍스트로만 간단하게 설명하는 것보다는, 그 아래에 이미지 형식의 개발 흐름도를 삽입한다면 독자들은 보다 명확한 이해를 할 수 있을 것입니다. 또한 개요에 간략한 설명과 이미지를 삽입한 후, 자세한 내용은 해당 챕터를 참고하라는 안내 문구도 삽입해 주면 독자 친화적인 개요를 완성할 수 있습니다.
마치며
지금까지 개요의 정의, 역할, 작성 방법, 작성 요령에 대해 소개해 드렸는데요. 개요는 해당 기술문서의 첫인상으로서 독자의 흥미를 유발하고, 본문을 요약하며 관련된 배경 지식을 전달한다는 측면에서 기술문서의 핵심이라고도 볼 수 있습니다. 그리고 이런 핵심을 잘 뽑아낸다는 것은 결코 쉬운 작업은 아닐 것입니다.
이제 이 글을 읽으신 분들은 기술문서를 읽을 때 개요가 자신의 역할을 충분히 하고 있는지, 해당 문서가 내가 원하는 문서가 맞는지, 본문 내용은 나의 기대 사항을 충족하고 있는지 등을 생각하시게 될 것입니다. 기술문서를 작성할 경우에는, 독자의 흥미를 유발하고, 본문을 요약하거나 독자에게 전달할 배경지식 등이 있는지 다시 한번 생각하고 개요를 작성하시면 좋을 것 같습니다.
테크니컬라이팅 팀에서 이렇게 "개요 작성의 중요성"이란 주제로 포스팅 한 면을 다루는 이유 역시 그만큼 개요 섹션이 중요하기 때문인데요. 지금까지 개요는 그저 문서의 구색 맞추기에 필요한 한 섹션으로 생각하셨다면, 이번 포스팅을 통해 개요의 중요성에 대해 곰곰이 생각해 보셨으면 좋겠습니다. 그럼 다음에 더 좋은 포스팅으로 찾아오겠습니다. 감사합니다.☺
📍 테크니컬 라이팅 관련 글 더보기
✓ 개발자들을 위한 테크니컬 라이팅 10계명
✓ 목차의 중요성
✓ 기술 문서 작성 5단계
✓ 테크니컬 라이팅 4대 원칙
✓ 기술 문서 쉽게 쓰기 지침
✓ 언어학 관점에서의 기술문서 가독성 향상 전략
✓ 카카오 i 기술문서 사이트 여정, 그리고 벌써 한 달
✓ Technical Writer에서 Technical Communicator로...
✓ [KREW INSIDE] AI 서비스의 기술 문서를 책임지는 사람들, 테크니컬 라이터
김유리(Crystal)
사용자의 입장에서 생각하고, 개발자와 원활한 소통을 할 수 있는 Communication Skill을 가진 Technical Communicator입니다. 카카오엔터프라이즈의 값진 기술들을 정확하고 명확하게 전달하고, 신뢰를 쌓을 수 있는 문서를 만들고자 합니다.
차신영(Sandy)
산더미처럼 쌓여진 문서 정리, 새로운 문서화 도구 테스트, 그리고 구글링이 취미인 Technical Communicator입니다.
댓글