문서 구조 만들기
여러 페이지로 구성된 문서를 작성할 때는 체계적인 문서 구조가 필요해요. 문서를 잘 설계하면 독자가 원하는 정보를 빠르게 찾고, 관련 내용을 자연스럽게 탐색할 수 있어요. 다음 세 가지 핵심 요소를 고려해야 해요.
TIP
- 문서 유형을 파악하고 독자의 목표에 맞는 문서를 작성해요.
- 문서 구조를 논리적으로 배치해서 흐름을 자연스럽게 만들어요.
- 크로스링크를 활용해서 독자가 관련 내용을 쉽게 찾을 수 있도록 해요.
문서 구조를 만드는 데에는 정답이 있는 건 아니에요. 내가 쓰고 싶은 문서 주제에 따라 독자 입장에서 어떤 문서가 필요할지 생각해 보고, 먼저 어떤 문서 유형이 필요할지부터 생각해 보세요.
1. 어떤 유형의 문서가 필요한지 파악하기
만들 문서를 구성할 각 유형과 문서의 계층 구조를 설계합니다. 예를 들면 초심자인 독자가 문서를 읽고 따라하는 것을 목표로 하는 문서, 문제 해결을 위한 문서, 개념을 설명하는 문서, 참고 자료를 제공하는 문서 등으로 나눠보는 거예요.
문서 유형에 대한 자세한 내용은 문서 유형 정하기 문서를 참고해 주세요.
2. 문서 구조 설계하기
어떤 문서 유형이 들어갈 지 정했다면 이제 문서 구조를 설계해요. 가장 쉽게 접근하는 방법은 문서의 왼쪽 내비게이션 메뉴를 짜본다고 생각하는 거예요.
만약 앞서 배운 모든 유형의 문서를 넣는다면 다음과 같이 구성할 수도 있어요.
docs/
├── tutorials/ # 학습 중심 문서
│ ├── getting-started.md # 전체적인 개요를 이해할 수 있는 시작하기
│ └── tutorial.md # 개발 흐름을 이해할 수 있는 튜토리얼
│
├── how-tos/ # 문제 해결 중심 문서
│ ├── configure-eslint.md # 구체적인 기능을 설명하는 가이드 e.g. ESLint 설정 방법
│ ├── fix-hydration-error.md # 자주 발생하는 구체적인 문제를 해결하기 위한 가이드 e.g. Next.js Hydration 오류 해결
│ └── optimize-react.md # 특정 목표를 달성하기 위한 가이드 e.g. React 렌더링 최적화 방법
│
├── explanations/ # 설명 문서
│ ├── virtual-dom.md # 개념을 설명하는 문서 e.g. Virtual DOM 개념
│ └── state-management.md # 특정 기술의 원리를 설명하는 문서 e.g. 상태 관리의 원리
│
├── reference/ # 참조 문서
│ ├── api-endpoints.md # API 엔드포인트 목록
│ └── error-codes.md # 오류 코드 목록
│ # 기타
├── troubleshooting.md # 에러 해결 가이드 (오류 코드 목록에서 통합해 제공할 수도 있음)
└── glossary.md # 용어 사전
이번에는 "Next.js 성능 최적화 가이드"라는 문서의 구조를 짜야 한다고 가정해 볼게요.
다음 구조를 보면 학습 중심 문서, 문제 해결 중심 문서, 설명 문서가 있어요. 기본적인 개념을 설명하고 튜토리얼로 일반적인 사용 방법을 설명한 뒤, 특정 목표를 달성하기 위한 가이드를 제공하죠.
nextjs-performance-optimization/
├── index.md # 개요 (Overview)
├── fundamentals.md # 성능 최적화의 기본 개념
├── tutorial.md # 성능 최적화를 적용하는 간단한 튜토리얼
├── guides/ # 특정 목표를 달성하기 위한 가이드
│ ├── code-splitting.md # e.g. 코드 분할 (Code Splitting)
│ └── image-optimization.md # e.g. 이미지 최적화
│ └── caching-strategies.md # e.g. 캐싱 전략
└── troubleshooting.md # 문제 해결 (Troubleshooting)
기존 문서 유형이나 템플릿에 너무 얽매이지 않고 유형을 조합해서 문서를 만들어도 돼요.
참고하세요
-
학습을 위한 문서는 전체적인 흐름과 개요를 이해하는 걸로 시작해요. 필요하다면 실습, 심화 문제 해결의 계층을 가질 수 있어요.
-
문제 해결을 위한 문서나 설명 문서의 구조는 단계적이지 않고 같은 레벨의 문서로 구성될 수 있어요.
-
참조 문서는 새로운 페이지에서 따로 목록을 제공할 수 있어요.
3. 연결 관계를 고려하여 크로스링크 설정하기
보통 이렇게 여러 문서로 이루어진 문서는 하나의 문서 안에서 끝나지 않고, 다른 문서와 연결될 때가 많아요.
예를 들면 튜토리얼에서 간단히 설명한 내용을 자세하게 설명하고 싶다면 가이드나 참조 문서의 링크를 추가해 주면 독자가 더 깊은 정보가 필요할 때 바로 원하는 정보를 찾을 수 있어요.
예를 들어, '코드 분할' 문서에서는 lazy-loading.md 문서를 참고 링크로 연결할 수 있겠죠.
nextjs-performance-optimization/
├── index.md
├── code-splitting.md
├── ...
└── lazy-loading.md # 코드 분할과 연계된 내용
이렇게 크로스링크를 추가하면 문서 간 연결성이 강화되고, 독자가 필요할 때 자연스럽게 관련 문서를 탐색할 수 있도록 합니다.
기본 템플릿
문서 구조를 만들 때 기본적인 템플릿을 참고해 보세요.
docs/
├── get-started.md
├── tutorials/ # 학습 중심 문서
│ ├── a-tutorial.md
│ └── another-tutorial.md
├── how-tos/ # 문제 해결 중심 문서
│ ├── a-how-to.md
│ └── another-how-to.md
├── explanations/ # 개념 설명 문서
│ ├── a-concept.md
│ └── a-topic.md
├── reference/ # 참조 문서
│ ├── an-element.md
│ └── another-element.md
├── troubleshooting.md # 문제 해결 (에러 해결 가이드)
└── glossary.md # 용어 사전
