|
1 | | -<!-- 문서 유형 + 프롬프트 --> |
| 1 | +<!-- "문서 유형을 어떻게 정하는지"에 초점을 맞추어 작성 --> |
| 2 | + |
| 3 | +# 문서 구조 만들기 |
| 4 | + |
| 5 | +AI에게 바로 “문서를 써줘”라고 지시하기보다, 먼저 **“이 문서는 어떤 유형의 문서이며, 어떤 목적을 가지고 어느 만큼의 정보를 다루는가”를 정의**하는 것이 중요해요. |
| 6 | +AI는 스스로 문서의 범위나 주제를 정하지 못하기 때문이에요. 이 때문에 꼭 필요한 정보가 누락되거나, 존재하지 않는 내용을 만들어내는 할루시네이션이 발생할 수도 있어요. |
| 7 | + |
| 8 | +문서 구조를 직접 설계하면 아래와 같은 이점이 있어요. |
| 9 | + |
| 10 | +- **정보의 우선순위가 명확해져요**: 어떤 내용을 중심으로 써야 하는지 결정할 수 있어요. |
| 11 | +- **불필요한 반복이나 누락을 방지해요**: AI가 다른 문서에서 이미 다룬 내용을 중복 생성하지 않아요. |
| 12 | +- **문서의 일관성이 유지돼요**: 이미 구조가 정의되어 있기 때문에 여러 사람이 AI를 이용해 작성하더라도 같은 구조를 따르게 돼요. |
| 13 | + |
| 14 | +이 문서에서는 문서 구조를 만들기 위해 어떤 단계를 거쳐야 하는지 설명해 볼게요. |
| 15 | + |
| 16 | +## 1. 문서 유형 정하기 |
| 17 | + |
| 18 | +문서의 유형을 정의하면 작성자는 어떤 내용을 포함해야 할지 쉽게 판단할 수 있고 AI가 문서의 톤과 구조를 혼동하지 않게 돼요. |
| 19 | + |
| 20 | +문서 유형을 정할 때는 아래의 의사결정 순서를 따라보세요. 문서 유형을 미리 결정하면 작성자 입장에서는 문서의 흐름과 구성 요소를 쉽게 잡을 수 있고, 독자 입장에서는 필요한 정보를 빠르게 찾을 수 있어요. |
| 21 | + |
| 22 | +기술 문서의 유형을 더 자세히 알고 싶다면 [문서 유형 알아보기](/comprehension/doc-type) 문서를 참고하세요. |
| 23 | + |
| 24 | + |
| 25 | + |
| 26 | +### 문서의 목적을 결정해요 |
| 27 | + |
| 28 | +이 문서를 통해 독자가 무엇을 하게 하려 하나요? 문서의 최종 목적을 한 문장으로 써보세요. 예를 들어 “Next.js 성능 최적화하는 방법 알아보기”, “API 응답 코드 확인하기”처럼 작성할 수 있어요. |
| 29 | + |
| 30 | +### 문서 유형을 선택해요 |
| 31 | + |
| 32 | +문서를 작성하는 의도를 독자에게 명확히 전달하려면, 문서의 목적에 맞는 유형을 선택해야 해요. 예를 들어 목적이 'Next.js 성능 최적화하는 방법'이라면 독자가 이 문서를 ‘단계적으로 배우는 가이드’로 인식할 수 있도록 구성해야 해요. |
| 33 | + |
| 34 | +<!-- 이 부분을 ~~라면? ~~를 선택하세요. 이런 식으로 고민 해결하듯이? 과정 중심으로 작성하고 싶은데 어떻게 풀어야 할지 모르겠음. --> |
| 35 | + |
| 36 | +::: details 학습을 위한 문서를 선택하는 경우 |
| 37 | + |
| 38 | +- 새로운 도구나 프레임워크의 사용법을 배워야 할 때 |
| 39 | +- 설치, 설정, 첫 실행 과정을 안내할 때 |
| 40 | +- 예시: [Next.js 시작하기](https://nextjs-ko.org/docs), [토스페이먼츠 개발자센터 - 결제 연동하기](https://docs.tosspayments.com/guides/v2/payment-widget/integration) |
| 41 | + |
| 42 | +::: |
| 43 | + |
| 44 | +::: details 문제 해결을 위한 문서를 선택하는 경우 |
| 45 | + |
| 46 | +- 이미 기술에 대해 알고 있는 상태에서 오류, 예외, 실패 사례를 다룰 때 |
| 47 | +- 예시: [Stripe Docs - Collect physical addresses](https://docs.stripe.com/payments/collect-addresses), [use-funnel - 퍼널 안에 퍼널 만들기](https://use-funnel.slash.page/ko/docs/sub-funnel) |
| 48 | + |
| 49 | +::: |
| 50 | + |
| 51 | +::: details 참조를 위한 문서를 선택하는 경우 |
| 52 | + |
| 53 | +- API, 컴포넌트 속성과 같은 정보를 제공할 때 |
| 54 | +- 예시: [es-toolkit 레퍼런스](https://es-toolkit.dev/ko/reference/array/at.html), [Spotify for Developers - oEmbed API](https://developer.spotify.com/documentation/embeds/reference/oembed) |
| 55 | + |
| 56 | +::: |
| 57 | + |
| 58 | +::: details 깊은 이해를 위한 문서를 선택하는 경우 |
| 59 | + |
| 60 | +- 복잡한 기술의 작동 원리를 설명해야 할 때 |
| 61 | +- 왜 이런 구조나 패턴을 선택했는지 배경을 전달할 때 |
| 62 | +- 예시: [MDN Web Docs - 웹의 동작 방식](https://developer.mozilla.org/ko/docs/Learn_web_development/Getting_started/Web_standards/How_the_web_works) |
| 63 | + |
| 64 | +::: |
| 65 | + |
| 66 | +## 2. 문서 구조 설계하기 |
| 67 | + |
| 68 | +문서 유형을 정했다면 이제 문서 구조를 설계해요. 문서 구조를 설계하는 건 **독자가 문서를 어떤 순서와 흐름으로 탐색할지 정하는 과정**이에요. 쉽게 생각해서 사이드바를 구성한다고 생각하면 돼요. |
| 69 | +그래서 구조를 만들 때는 정보의 논리적 순서와 독자의 학습 흐름을 함께 고려해야 해요. |
| 70 | + |
| 71 | +### 기본 구조 예시 |
| 72 | + |
| 73 | +아래의 구조는 대부분의 기술 문서에서 공통적으로 사용되는 패턴이에요. 이런 식으로 기존 문서 유형이나 템플릿에 너무 얽매이지 않고 문서의 목적과 독자의 여정을 고려해 여러 유형을 조합해도 돼요. |
| 74 | + |
| 75 | +이런 구성으로 사이드바를 설계하면, 독자는 ‘개념 정리 → 학습 → 적용 → 문제 해결’ 순서로 정보를 탐색할 수 있어요. |
| 76 | + |
| 77 | +``` |
| 78 | +docs/ |
| 79 | +├── get-started.md |
| 80 | +├── explanations/ # 개념 설명 문서 |
| 81 | +│ ├── a-concept.md |
| 82 | +│ └── a-topic.md |
| 83 | +├── tutorials/ # 학습 중심 문서 |
| 84 | +│ ├── a-tutorial.md |
| 85 | +│ └── another-tutorial.md |
| 86 | +├── reference/ # 참조 문서 |
| 87 | +│ ├── an-element.md |
| 88 | +│ └── another-element.md |
| 89 | +├── troubleshooting.md # 문제 해결 문서 (에러 해결 가이드) |
| 90 | +└── glossary.md # 용어 사전 |
| 91 | +``` |
| 92 | + |
| 93 | +예를 들어 "Next.js 성능 최적화 가이드"라는 문서의 구조를 짜야 한다고 가정해 볼게요. |
| 94 | + |
| 95 | +다음 구조를 보면 학습 중심 문서, 문제 해결 중심 문서, 설명 문서가 있어요. 기본적인 개념을 설명하고 튜토리얼로 일반적인 사용 방법을 설명한 뒤, 특정 목표를 달성하기 위한 가이드를 제공하죠. |
| 96 | + |
| 97 | +이렇게 하면 독자는 기본 개념을 이해하고 튜토리얼로 실습한 다음, 세부 목표별로 최적화 방법을 찾아볼 수 있어요. |
| 98 | + |
| 99 | +``` |
| 100 | +nextjs-performance-optimization/ |
| 101 | +├── index.md # 개요 (Overview) |
| 102 | +├── fundamentals.md # 성능 최적화의 기본 개념 |
| 103 | +├── tutorial.md # 성능 최적화를 적용하는 간단한 튜토리얼 |
| 104 | +├── guides/ # 특정 목표를 달성하기 위한 가이드 |
| 105 | +│ ├── code-splitting.md # e.g. 코드 분할 (Code Splitting) |
| 106 | +│ └── image-optimization.md # e.g. 이미지 최적화 |
| 107 | +│ └── caching-strategies.md # e.g. 캐싱 전략 |
| 108 | +└── troubleshooting.md # 문제 해결 (Troubleshooting) |
| 109 | +``` |
| 110 | + |
| 111 | + |
| 112 | +## ✅ 체크리스트 |
| 113 | +가이드를 바탕으로 문서의 구조를 설계해 봤다면, 문서가 잘 구성되었는지 아래 질문으로 점검해보세요. |
| 114 | + |
| 115 | +- [ ] 사이드바를 확인하면 어떤 주제를 다루고자 하는지 알 수 있나요? |
| 116 | +- [ ] 카테고리, 페이지 이름이 일관되고 의미가 명확한가요? |
| 117 | +- [ ] 동일한 유형의 문서가 한 카테고리 안에 모여 있나요? |
| 118 | +- [ ] 시작하기, 용어 정리 같은 보조 문서의 위치가 적절한가요? |
0 commit comments