Technical Writing Two - 문서 구조화 하기 (2) 목차와 탐색

Google Technical Writing 과정 정리의 마지막 포스팅입니다.

문서의 구성이 좋다는 것은 기술 문서의 사용자가 필요한 내용을 빠르게 찾고 이해하기 쉽도록 각각 주제들이 논리적으로 연결된 것을 의미한다고 합니다. 이번 포스팅에서는 문서를 구조화할 때 목차를 어떻게 작성해야 하는지 탐색 기능을 왜 추가해야 하는지에 대해서 작성해보려고 합니다. 

---

목차 

목차는 기술문서의 필수 요소로써 독자에게 기술문서의 구성을 한눈에 보여주는 아주 중요한 역할을 합니다. 5장 이내의 짧은 문서라면 목차를 반드시 작성하지 않아도 되지만 매뉴얼과 같이 몇 백 페이지가 넘어가는 긴 문서는 목차를 작성해주어야 독자가 피요한 정보를 빠르게 찾을 수 있습니다. 

매뉴얼 작성 시에 항상 생각해야 하는 것 중에 하나는 긴 매뉴얼을 처음부터 끝까지 정독하는 독자는 없다는 것입니다. 즉, 사용자는 목차를 보고 필요한 정보만 찾는 경우가 많다는 것입니다. 구글에서는 잘 구성된 목차가 사용자가 도구의 기능을 탐색하는 데 도움이 되는 지도와 같은 역할을 한다고 말하고 있습니다. 

저는 목차 작성 시 고려해야할 사항을 다음과 같이 정리하고 있습니다. 

• 목차는 3수준(1.1.1)까지 작성하는 것이 좋습니다. 필요한 경우에는 최대 4 수준까지만 작성할 수 있도록 합니다. 
• 각 제목 수준에 맞는 제목 스타일을 사용합니다. 
• 비슷한 내용을 같은 카테고리로 그룹화합니다.
• 일련의 과정이 있는 경우 그 과정대로 목차 순서를 배치합니다. 예를 들어 프로그램 설치 과정을 설명하는 매뉴얼일 경우에는 프로그램 설치 순서대로 목차를 구성합니다. 
• 서로 중복되는 내용을 피하되 전체적으로 누락은 없도록 주의합니다.
• 목차 작성 시에 약어 사용을 자제합니다.
• 워드 혹은 pdf에서 작성 시에 상호 참조 기능을 사용해 목차를 클릭하면 해당 장으로 바로 이동할 수 있도록 합니다. 

 

여기서 비슷한 내용을 같은 카테고리로 그룹화하는 것에 대해서 구체적으로 설명해보고자 합니다.

 

주제 분류하기

구글에서 목차를 분류할 수 있는 연습을 해볼 수 있도록 다음과 같은 예시를 제공하고 있는데요. 주제를 분류해보고 왜 이렇게 분류했는지 설명해보겠습니다. 오른쪽에 나열된 주제를 왼쪽과 같이 재 정렬해봤습니다. 

• 서두에는 이 튜토리얼 문서가 누구를 대상으로 하는지, 목적은 무엇인지를 알 수 있도록 배치해두었습니다. 서두에는 문서를 사용하기 위한 기본 배경 지식에 대한 설명, 정의, 사용 목적 등이 포함될 수 있습니다.
  
  
• 본문에는 실제로 문서를 보면서 할 수 있는 동작들을 작성합니다. 여기서 저는 튜토리얼 Setting을 먼저 하고 프로젝트를 정의하는 사용자가 사용하는 순서대로 배치해봤습니다. 
  
  
• 참고에는 반드시 필요한 요구사항이 아닌 나머지 항목들을 작성할 수 있습니다. 

출처: 본인

본문에 가장 많은 내용이 들어가는 만큼 본문의 구조를 짜임새 있게 작성하는 것이 가장 어렵다고 생각이 듭니다. 작성할 때 사용자가 실제로 사용하는 동작 중심으로 먼저 크게 일련의 단계를 나누어 초안을 작성해보면 보다 쉽게 목차를 작성할 수 있지 않을까요? 

 

 

행동 중심의 제목 부여하기 

목차의 제목을 작성할 때는 독자가 작업 중인 동작을 설명하는 제목을 부여합니다.

예를 들어 많은 데이터를 일괄적으로 Fitting 하는 기능에 대해서 설명한다고 가정해보겠습니다. 그럼 제목을 어떻게 부여하는 것이 좋을까요? 저는 '데이터 한 번에 Fitting 하기'라고 직관적으로 작성해봤습니다. '데이터 Fitting'이라고 작성하면 이미 앞단에 비슷한 내용이 있었고 해당 내용은 한 번에 일괄적으로 Fitting 하기에 중심이 맞춰져 있다고 생각했습니다. '데이터 일괄적으로 Fitting 하기'라고 작성해도 되겠지만 일괄적으로 보다는 보다 쉬운 용어로 작성하고자 했습니다. 

아래는 카카오 디벨로퍼의 목차 예시입니다. 카카오 디벨로퍼에서도 작업 중인 동작 중심으로 제목이 작성되어있는 것을 확인할 수 있습니다. 

출처: 카카오 디벨로퍼

 

 

제목 아래에 내용 작성하기

제목 아래에 소개될 내용을 간략하게 작성해 다음에 설명할 내용이 무엇인지 독자에게 알려줄 수 있습니다. 예를 들어 다음과 같이 제목 1 수준 뒤에 바로 제목 2 수준을 배치하는 것을 권장하지 않습니다. 

(Before)
1. 사이트 만들기
1.1 Carambola 명령 실행
본문

(After)
1. 사이트 만들기
사이트를 만들기 위해서는 'Carambola' 명령어를 실행해야 합니다. 이 명령은 사이트 구성에 도움이 되는 일련의 프롬프트를 표시합니다.

1.1 Carambola 명령 실행​
본문

1. 사이트 만들기의 아래에 개요 글을 작성해 사이트를 만들기 위해 어떤 명령어를 왜 실행해야 하는지 설명해주고 있습니다. 개요 글이 있으면 독자는 다음에 무슨 내용이 소개될지 예측할 수 있습니다. 

 

탐색

문서의 독자를 위한 탐색과 색인을 제공하면 방대한 문서에서 독자가 원하는 내용을 빠르고 쉽게 찾을 수 있습니다. 명확한 탐색을 위해서는 다음과 같은 내용이 포함될 수 있습니다. 

• 소개 및 요약 섹션
• 주제의 명확하고 논리적인 전개
• 사용자가 주제를 이해하는 데 도움이 되는 제목
• 문서에서 사용자의 위치를 보여주는 목차 메뉴
• 관련 리소스 또는 더 자세한 정보에 대한 링크
• 다음에 배울 내용에 대한 링크

 

여기서 더 자세한 정보에 대한 링크나 문서에서 사용자의 위치를 보여주는 목차 메뉴 등은 웹 환경에서 많이 사용되고는 합니다. 아래는 핵클 사용자 가이드 예시입니다. 오른쪽에 해당 페이지의 목차가 나타난 것을 확인할 수 있습니다. 독자가 지금 어디를 읽고 있는지 다음에는 무슨 내용이 나오는지 파악할 수 있습니다. 또한 더 자세한 정보에 대한 링크를 제공하기도 합니다. 

출처: 핵클 사용자 가이드

 

워드로 문서를 작성하는 경우에는 이 내용은 몇 장을 참고하세요 라고 상호 참조를 걸어줄 수 있습니다. 

---

목차가 작성된 후에는 목차의 구성과 내용을 검토해야 합니다. 사용자가 필요한 내용을 쉽게 찾을 수 있도록 목차가 효과적으로 구성되어있는지, 사용자가 필요로 하는 정보가 누락되지는 않았는지, 링크가 적절하게 연결되어 있는지 등을 확인할 수 있겠죠?

문서를 작성하는 도구와 유형에 상관없이 목차는 가장 중요하다고 생각이 듭니다. 처음에 목차의 초안을 구성해두지만 본문을 작성할 때는 조금씩 구성이 바뀌고는 합니다😅