docs: 문서 이름 수정, #22 리뷰 반영

Author: aoqlsdl

docs/arrange/architecture.md

@@ -0,0 +1,159 @@
+# 문서 구조 만들기
+
+좋은 기술 문서를 작성하기 위해 가장 먼저 고려해야 할 것은 문서의 구조예요.
+독자는 문서를 처음 읽을 때 모든 정보를 한 번에 이해하기 어려워요. 그래서 정보를 논리적이고 이해하기 쉬운 구조로 설계하는 것이 중요해요. 구조가 잘 짜여 있으면 독자가 어떤 순서로 내용을 읽고, 어디에서 필요한 정보를 찾을 수 있는지 직관적으로 알 수 있어요.
+
+또, AI를 사용해서 초안을 작성할 때도 도움이 돼요. 이때 **문서 구조 설계를 AI에게 맡기기보다는 직접 고민하는 것이 좋아요.**  
+문서의 목적과 다루어야 할 정보의 범위를 가장 잘 아는 사람은 작성자 자신이기 때문이에요.
+
+AI는 스스로 문서의 주제나 범위를 판단할 수 없어요. 사용자가 구조를 제시하지 않으면 꼭 필요한 정보가 빠지거나, 실제로 존재하지 않는 내용을 만들어내는 할루시네이션(hallucination)이 발생할 수 있어요.  
+
+따라서 문서 구조는 직접 설계하고, 그 구조를 바탕으로 AI에게 초안을 작성해 달라고 지시하는 방식이 효율적이에요.
+
+이제 문서 구조를 만들기 위해 어떤 단계를 거쳐야 하는지 설명해 볼게요.
+
+::: tip 문서 구조를 만들고 나서 AI와 함께 검토해 보세요
+직접 문서 구조를 만든 다음 설계한 구조가 적절한지 확인해달라고 AI에게 요청할 수 있어요.  
+이렇게 하면 문서를 작성하는 목표는 유지하면서 더 보기 좋은 문서를 만들 수 있어요.  
+자세한 내용은 [AI와 함께 검토하기](/url) 문서를 확인하세요.
+:::
+
+## 1. 문서의 목적 정의하기
+
+이 문서를 통해 **독자가 무엇을 할 수 있게 만들고 싶은지**를 한 문장으로 써보세요. 
+예를 들어 다음과 같이 쓸 수 있어요.
+
+- 이 문서를 읽고 Next.js 성능을 직접 최적화할 수 있다.
+- 토스 페이먼츠의 결제하기 API를 이해하고 직접 요청을 보내 결제를 완료할 수 있다.
+- API의 요청 형식과 응답 구조를 정확히 이해하고 사용할 수 있다.
+- React의 가상 DOM이 렌더링 성능에 어떤 영향을 주는지 이해할 수 있다.
+
+이렇게 문서의 목적을 정리하면 다음 단계에서 문서 유형을 선택하는 기준으로 삼을 수 있어요. 
+
+## 2. 문서 유형 정하기
+
+목적을 정의했다면, 이제 그 목적을 달성하기에 가장 적합한 문서 유형을 선택하세요.
+문서 유형을 정하면 독자의 목표와 학습 흐름에 맞춰 문서 구조를 설계할 수 있어요. 
+
+문서 유형은 작성자가 정보를 **어떤 목적을 가진 독자에게 전달하려는지**에 따라 달라져요.  
+같은 주제라도 문서 유형에 따라 문서 구조와 페이지 작성 방식이 다를 수 있어요. 따라서 문서를 작성하기 전에 "이 문서는 어떤 독자를 위한 것인가?"를 먼저 생각하는 것이 좋아요.  
+
+아래 과정을 따라 어떤 문서 유형이 적합한지 결정해 보세요.
+
+![문서 유형 의사결정 트리](../public/resources/decision-tree.png)
+
+### 기본부터 이해하기를 원할 때
+
+**학습을 위한 문서를** 선택하세요. 학습을 위한 문서는 기술을 처음 접하는 독자가 개념과 사용 흐름을 익히고, 설치나 설정 과정을 따라 할 수 있도록 안내하는 데 적합해요.
+시작하기 문서나 튜토리얼 문서가 이 유형에 해당해요.
+
+앞서 문서의 목적을 "이 문서를 읽고 Next.js 성능을 직접 최적화할 수 있다."로 정했다면 **튜토리얼 문서**로 작성하면 돼요.  
+튜토리얼 문서에서는 "무엇을 배우는가"보다 "어떻게 따라 하면 되는가"에 초점을 맞추는 게 좋아요.
+
+### 특정 문제를 해결하기를 원할 때
+
+**문제 해결을 위한 문서**를 선택하세요. 이 유형은 이미 기술을 사용해 본 독자가 오류나 예외 상황을 해결하려고 할 때 도움이 돼요.
+How-to 가이드나 트러블 슈팅, FAQ 문서가 여기에 해당해요.
+
+문서의 목적을 "토스 페이먼츠의 결제하기 API를 이해하고 직접 요청을 보내 결제를 완료할 수 있다."로 정했다면 **How-to 가이드**로 만들면 돼요.  
+문제 해결 문서는 문제 상황 → 원인 → 해결 방법 순서로 구성하는 게 효과적이에요.
+
+### 특정 기능이나 API 사용법을 전달할 때
+
+**참조를 위한 문서**를 선택하세요. 참조를 위한 문서는 독자가 빠르게 특정 기능의 사용법이나 속성, 옵션 등을 확인할 때 유용해요. 
+API 레퍼런스나 에러 코드 목록이 이 유형에 포함돼요.
+
+예를 들어 문서의 목적을 "S3에 이미지 업로드를 하는 API의 요청 형식과 응답 구조를 정확히 이해하고 사용할 수 있다."로 정했다면 **API 레퍼런스**로 작성하면 돼요.  
+
+참조 문서는 일반적으로 페이지에 들어갈 내용이 정해져 있어요. 요청 메서드, 엔드포인트, 파라미터, 응답 값, 예제 순으로 구성하면 독자가 빠르게 정보를 탐색할 수 있어요. 
+
+### 특정 개념을 깊이 설명하고 싶을 때
+
+**깊은 이해를 위한 문서**를 선택하세요. 이 유형은 기술의 기본적인 사용법을 이미 알고 있는 독자를 대상으로, 기술의 동작 원리나 설계 철학을 설명할 때 적합해요.  
+
+문서의 목적을 "React의 가상 DOM이 렌더링 성능에 어떤 영향을 주는지 이해할 수 있다."로 정한 경우가 여기에 해당해요.  
+이런 문서는 개념을 깊이 이해하고 싶은 독자를 위해 배경, 원리, 비교, 장단점 중심으로 구성하면 좋아요.
+
+## 3. 문서 구조 설계하기
+
+문서 유형을 정했다면 이제 문서 구조를 설계해요. 문서 구조를 만들 때는 정보의 논리적 순서와 독자의 학습 흐름을 함께 고려해야 해요. 왜냐하면 독자는 정해진 문서 구조를 따라 탐색하고 학습하기 때문이에요.
+
+조금 더 쉽게 생각하고 싶다면 일단 사이드바를 한 번 구성해 보세요.
+사이드바는 문서의 전체 구조를 시각적으로 보여 주기 때문에, 이 단계에서 큰 틀을 설계하면 이후 작성 과정이 훨씬 수월해요.
+
+### 하나의 주제를 중심으로 구성하기
+
+좋은 문서 구조는 **문서의 목적이 한눈에 드러나는 구조**예요. 즉, “이 문서는 어떤 주제를 중심으로 다루는가”를 독자가 바로 파악할 수 있도록 구성해야 해요. 
+
+가장 중요하게 다룰 주제를 먼저 정한 뒤, 그 주제를 완성하기 위해 필요한 문서들을 자연스럽게 이어 붙이면 돼요.  
+예를 들어 중심 주제가 ‘결제 연동하기’라면, 그 아래에 ‘API 키 발급’, ‘요청 보내기’, ‘응답 처리’ 같은 하위 문서를 배치하는 식이에요.
+
+아래의 문서 구조는 대부분의 기술 문서에 적용할 수 있는 **기본적인 구조 패턴**이에요.
+main-theme/ 디렉토리 안에서 하나의 핵심 주제를 다루고, 나머지 문서는 독자가 참고하거나 문제를 해결할 때 찾아볼 수 있는 보조 정보로 구성해요.
+
+```
+docs/
+├── get-started.md              # 시작하기
+├── main-theme/                 # 중심 주제
+│   ├── topic-or-step-1.md
+│   └── topic-or-step-2.md
+└── supplementary-docs.md       # 용어 사전·문제 해결·참조 문서 등 보조 문서
+```
+
+이 구조를 활용하면 독자가 무엇부터 읽고, 어떤 순서로 따라가야 하는지를 직관적으로 이해할 수 있어요.  
+또한 새로운 문서를 추가하거나 갱신할 때도 전체 구조를 일관되게 유지하기가 쉬워요.
+
+### 구성 예시
+
+이제 단일 주제를 중심으로 문서 구조를 설계하는 예시를 살펴볼게요.  
+
+학습문서인 ~~ Next.js의 성능 최적화 가이드를 작성한다면,(<--이런 식으로 문서 목적, 유형 모두 언급) `nextjs-performance-optimization/`이라는 하나의 카테고리를 중심으로 문서를 구성하는 거에요.  
+이 카테고리 안에서는 성능 최적화 방법을 단계적으로 설명하고, 그 주제를 이해하거나 실습하는 데 필요한 문서만 포함해요.
+
+이렇게 구조를 짜다 보면, 구체적인 가이드를 제시하기 전에 먼저 "성능 최적화가 무엇인지"를 설명해야 한다는 점을 알게 돼요.  
+또한 독자가 가이드를 따라 하다가 막힐 수 있는 부분을 예상해, 문제 해결 문서(troubleshooting)가 필요하다는 것도 판단할 수 있어요.  
+문서 구조를 직접 설계하는 과정에서 독자가 어떤 순서로 학습하고 어떤 지점에서 어려움을 느낄지 미리 파악하는 거에요.
+
+이렇게 하면 문서의 품질이 높아지고, 독자는 흐름에 맞게 자연스럽게 학습할 수 있어요.
+
+```
+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)
+```
+
+::: warning 모든 문서가 하나의 주제 중심으로 구성되지는 않아요.
+문서 구조는 단일 주제를 중심으로 만드는 게 기본이지만, 여러 주제를 한꺼번에 다루는 경우도 있어요.
+특히 서비스나 프레임워크 전체를 다루는 개발자 문서라면 튜토리얼, 문제 해결, 참조, 개념 문서가 모두 중요한 역할을 하죠.
+
+이런 경우에는 독자의 탐색 흐름을 고려해서 여러 가지 주제를 논리적인 순서대로 배치해 보세요.
+```
+docs/
+├── get-started.md
+├── explanations/     # 개념 설명 문서
+│   ├── concept.md
+│   └── topic.md
+├── tutorials/        # 학습 중심 문서
+│   ├── basic-tutorial.md
+│   └── advanced-tutorial.md
+├── reference/        # 참조 문서
+│   ├── api.md
+│   └── component.md
+├── troubleshooting.md  # 문제 해결 문서
+└── glossary.md         # 용어 사전
+```
+:::
+
+## ✅ 체크리스트
+가이드를 바탕으로 문서의 구조를 설계해 봤다면, 문서가 잘 구성되었는지 아래 질문으로 점검해보세요.
+
+- [ ] 사이드바를 확인하면 어떤 주제를 다루고자 하는지 알 수 있나요?
+- [ ] 카테고리, 페이지 이름이 일관되고 의미가 명확한가요?
+- [ ] 동일한 유형의 문서가 한 카테고리 안에 모여 있나요?
+- [ ] 시작하기, 용어 정리 같은 보조 문서의 위치가 적절한가요?

docs/arrange/type.md

@@ -87,7 +87,7 @@ export default defineConfig({
             },
             {
               text: '문서 구조 만들기',
-              link: '/arrange/type',
+              link: '/arrange/architecture',
             },
             {
               text: '자료 모으기',