@@ -85,11 +85,13 @@ API 레퍼런스나 에러 코드 목록이 이 유형에 포함돼요.
8585
8686좋은 문서 구조는 ** 문서의 목적이 한눈에 드러나는 구조** 예요. 즉, “이 문서는 어떤 주제를 중심으로 다루는가”를 독자가 바로 파악할 수 있도록 구성해야 해요.
8787
88- 가장 중요하게 다룰 주제를 먼저 정한 뒤 , 그 주제를 완성하기 위해 필요한 문서들을 자연스럽게 이어 붙이면 돼요.
89- 예를 들어 중심 주제가 ‘결제 연동하기’라면, 그 아래에 ‘API 키 발급’, ‘요청 보내기’, ‘응답 처리’ 같은 하위 문서를 배치하는 식이에요.
88+ 그렇게 하기 위해서 가장 중요하게 다룰 주제를 먼저 정한 다음 , 그 주제를 완성하기 위해 필요한 문서들을 이어 붙여요.
89+ 예를 들어 중심 주제가 ‘결제 연동하기’라면, 그 아래에 ‘API 키 발급’, ‘요청 보내기’, ‘응답 처리’ 같은 하위 문서를 순서대로 배치하는 식이에요.
9090
9191아래의 문서 구조는 대부분의 기술 문서에 적용할 수 있는 ** 기본적인 구조 패턴** 이에요.
92- main-theme/ 디렉토리 안에서 하나의 핵심 주제를 다루고, 나머지 문서는 독자가 참고하거나 문제를 해결할 때 찾아볼 수 있는 보조 정보로 구성해요.
92+ ` main-theme/ ` 디렉토리 안에서 하나의 핵심 주제를 다루고, 나머지 문서는 독자가 참고하거나 문제를 해결할 때 찾아볼 수 있는 보조 정보로 구성해요.
93+
94+ 이 구조를 활용해서 문서를 작성하면 독자가 무엇부터 읽고, 어떤 순서로 따라가야 하는지를 직관적으로 이해할 수 있어요. 새로운 문서를 추가하거나 갱신할 때도 전체 구조를 일관되게 유지하기가 쉬워요.
9395
9496```
9597docs/
@@ -100,18 +102,17 @@ docs/
100102└── supplementary-docs.md # 용어 사전·문제 해결·참조 문서 등 보조 문서
101103```
102104
103- 이 구조를 활용하면 독자가 무엇부터 읽고, 어떤 순서로 따라가야 하는지를 직관적으로 이해할 수 있어요.
104- 또한 새로운 문서를 추가하거나 갱신할 때도 전체 구조를 일관되게 유지하기가 쉬워요.
105+
105106
106107### 구성 예시
107108
108- 이제 단일 주제를 중심으로 문서 구조를 설계하는 예시를 살펴볼게요 .
109+ 예시로 Next.js 성능 최적화 가이드를 작성해 볼게요. 이 문서의 목적은 ** Next.js의 성능을 직접 개선할 수 있도록 돕는 것 ** 이에요. 따라서 문서 유형은 ** 튜토리얼 중심의 학습 문서 ** 가 돼요 .
109110
110- 학습문서인 ~~ Next.js의 성능 최적화 가이드를 작성한다면,(<--이런 식으로 문서 목적, 유형 모두 언급) ` nextjs-performance-optimization/ ` 이라는 하나의 카테고리를 중심으로 문서를 구성하는 거에요 .
111+ 이 경우 ` nextjs-performance-optimization/ ` 이라는 카테고리를 중심으로 문서를 구성하면 돼요 .
111112이 카테고리 안에서는 성능 최적화 방법을 단계적으로 설명하고, 그 주제를 이해하거나 실습하는 데 필요한 문서만 포함해요.
112113
113- 이렇게 구조를 짜다 보면, 구체적인 가이드를 제시하기 전에 먼저 " 성능 최적화가 무엇인지"를 설명해야 한다는 점을 알게 돼요.
114- 또한 독자가 가이드를 따라 하다가 막힐 수 있는 부분을 예상해, 문제 해결 문서(troubleshooting)가 필요하다는 것도 판단할 수 있어요.
114+ 이렇게 구조를 짜다 보면 구체적인 가이드를 제시하기 전에 먼저 성능 최적화가 무엇인지 설명하는 문서가 필요하다는 것을 알 수 있어요.
115+ 또한 독자가 가이드를 따라 하다가 막힐 수 있는 부분을 예상해, 트러블 슈팅 문서가 필요하다는 것도 판단할 수 있어요.
115116문서 구조를 직접 설계하는 과정에서 독자가 어떤 순서로 학습하고 어떤 지점에서 어려움을 느낄지 미리 파악하는 거에요.
116117
117118이렇게 하면 문서의 품질이 높아지고, 독자는 흐름에 맞게 자연스럽게 학습할 수 있어요.
0 commit comments