이 문서에서는 가장 기본적인 문서인 튜토리얼과 트러블슈팅 문서를 작성하는 방법을 알려드려요. 문서를 작성할 때 주의해야 할 점과 개선할 수 있는 부분을 함께 살펴봐요.
이 문서에서는 React를 처음 접하는 초보 개발자를 대상으로 'React 컴포넌트 만들기'라는 튜토리얼을 개선해 볼 거예요. 개선 전과 개선 후를 비교하면서 어떤 부분이 개선됐는지 살펴보세요.
참고하세요
학습을 위한 문서는 독자가 새로운 기술이나 도구를 배울 수 있도록 돕는 문서예요. 이 문서에서는 구체적인 예시, 실행 가능한 코드, 성공적인 경험을 제공해야 해요.
# React 컴포넌트 만들기
React 컴포넌트를 만드는 방법을 알아봅시다.
## 함수형 컴포넌트
함수형 컴포넌트는 다음과 같이 만듭니다.
function Welcome() {
return <h1>Hello</h1>;
}
## Props 사용하기
props를 사용하면 컴포넌트에 데이터를 전달할 수 있습니다.
function Welcome(props) {
return <h1>Hello, {props.name}</h1>;
}- 문서의 목적과 학습 목표가 명확하지 않아요. 독자가 이 문서를 읽고 어떤 결과를 기대할 수 있는지 한눈에 파악하기 어려워요
- 예제를 실행하기 어렵고, 실제 사용 맥락도 부족해요. 예제는 실제로 실행했을 때 작동하고, 이해도를 높이는 내용이어야 해요
- 갑자기 Props라는 개념이 나왔어요. 앞 부분과 이어지는 설명이 부족해서 단계별로 학습하기 어려워요. 개념을 먼저 이해하고, 단계별로 따라 하면서 자연스럽게 학습할 수 있어야 해요.
- 학습 목표를 명확하게 제시하고, 목표 → 준비 → 실습 → 적용 → 확장이라는 단계별 흐름을 통해 학습자가 쉽게 따라갈 수 있도록 개선했어요.
- 핵심 흐름에 집중해 예상 가능한 성공 경로를 중심으로 설명했고, 복잡하거나 부가적인 내용은 최소화하거나 별도로 안내했어요.
- 모든 코드 예제가 실제로 실행 가능하도록 설계되었고, 바로 복사해서 사용할 수 있어 실습 효율을 높였어요.
이 문서에서는 특정한 질문이나 이슈를 해결하기 위한 문서를 개선해 볼 거예요. 개선 전과 개선 후를 비교하면서 어떤 부분이 개선됐는지 살펴보세요.
참고하세요
문제 해결을 위한 문서는 독자가 특정한 문제를 해결하기 위한 문서예요. 이 문서에서는 문서가 해결하려는 문제, 질문을 명확히 하고 해결 방법을 구체적으로 제시해줘야 해요.
# Hydration 오류 해결하기
Next.js에서 클라이언트와 서버의 렌더링 결과가 불일치하면 Hydration 오류가 발생할 수 있어요. React에서는 `useEffect`를 활용해 특정 데이터를 클라이언트에서만 다르게 처리할 수 있습니다.
## 해결 방법
function TimeComponent() {
const [time, setTime] = useState(0);
useEffect(() => {
setTime(Date.now());
}, []);
return <p>현재 시간: {time}</p>;
}
`useEffect`를 사용하여 클라이언트에서만 특정 코드를 실행하도록 수정하고, 서버 렌더링과 클라이언트 렌더링이 동일한 결과를 출력하도록 코드를 수정해요.- 문서의 목표가 불분명해요. Hydration 오류가 무엇인지 정보가 없고, 해결 방법이 구조적으로 정리되지 않았어요.
- 설명과 코드 예제의 흐름이 자연스럽지 않아요. 코드가 먼저 등장해서 인지 부하가 생겨요.
여러 페이지로 구성된 문서를 작성할 때는 체계적인 문서 구조가 필요해요. 문서를 잘 설계하면 독자가 원하는 정보를 빠르게 찾고, 관련 내용을 자연스럽게 탐색할 수 있어요. 다음 세 가지 핵심 요소를 고려해야 해요.
TIP
- 문서 유형을 파악하고 독자의 목표에 맞는 문서를 작성해요.
- 문서 구조를 논리적으로 배치해서 흐름을 자연스럽게 만들어요.
- 크로스링크를 활용해서 독자가 관련 내용을 쉽게 찾을 수 있도록 해요.
문서 구조를 만드는 데에는 정답이 있는 건 아니에요. 내가 쓰고 싶은 문서 주제에 따라 독자 입장에서 어떤 문서가 필요할지 생각해 보고, 먼저 어떤 문서 유형이 필요할지부터 생각해 보세요.
만들 문서를 구성할 각 유형과 문서의 계층 구조를 설계합니다. 예를 들면 초심자인 독자가 문서를 읽고 따라하는 것을 목표로 하는 문서, 문제 해결을 위한 문서, 개념을 설명하는 문서, 참고 자료를 제공하는 문서 등으로 나눠보는 거예요.
문서 유형에 대한 자세한 내용은 문서 유형 정하기 문서를 참고해 주세요.
어떤 문서 유형이 들어갈 지 정했다면 이제 문서 구조를 설계해요. 가장 쉽게 접근하는 방법은 문서의 왼쪽 내비게이션 메뉴를 짜본다고 생각하는 거예요.
만약 앞서 배운 모든 유형의 문서를 넣는다면 다음과 같이 구성할 수도 있어요.
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)
기존 문서 유형이나 템플릿에 너무 얽매이지 않고 유형을 조합해서 문서를 만들어도 돼요.
참고하세요
- 학습을 위한 문서는 전체적인 흐름과 개요를 이해하는 걸로 시작해요. 필요하다면 실습, 심화 문제 해결의 계층을 가질 수 있어요.
- 문제 해결을 위한 문서나 설명 문서의 구조는 단계적이지 않고 같은 레벨의 문서로 구성될 수 있어요.
- 참조 문서는 새로운 페이지에서 따로 목록을 제공할 수 있어요.
보통 이렇게 여러 문서로 이루어진 문서는 하나의 문서 안에서 끝나지 않고, 다른 문서와 연결될 때가 많아요.
예를 들면 튜토리얼에서 간단히 설명한 내용을 자세하게 설명하고 싶다면 가이드나 참조 문서의 링크를 추가해 주면 독자가 더 깊은 정보가 필요할 때 바로 원하는 정보를 찾을 수 있어요.
예를 들어, '코드 분할' 문서에서는 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 # 용어 사전
문서를 쓰고 싶은데, 어디서부터 시작해야 할지 모르겠다면 다음 프롬프트로 시작해 보세요. 한꺼번에 모든 프롬프트를 넣기보다는 스텝별 봇을 만들어서 사용해야 답변이 잘 나와요.
INFO 프롬프트를 활용한 결과가 완벽하지는 않아요. 참고용으로 사용하세요.
- ChatGPT에서 오른쪽 위 아이콘을 누른 뒤 메뉴에서 '내 GPT'를 선택하세요.
- 'GPT 만들기'를 선택하세요.
- '구성' 탭에서 봇 이름을 정하고, '지침'에 아래 프롬프트를 추가하세요. 여기서는 문장 다듬기 프롬프트를 추가해 볼게요.
- 왼쪽 아래에 있는 '기능'은 전부 선택을 해제하세요.
- 프롬프트를 추가했다면 오른쪽 위 '업데이트' 버튼을 눌러보세요. 모달이 나오면 'GPT 보기'를 선택하세요.
- 기술 문서 문장 다듬기 봇이 완성됐어요.
- 다음과 같이 문장을 다듬어 보세요. 긴 문서도, 문장이나 문단도 전부 리뷰해줘요.
어떤 문서를 써야할지 모르겠다면 Step 1. 문서 유형 정하기의 프롬프트를 사용해 보세요. 프롬프트를 적용한 봇에 내가 쓴 문서, 혹은 생각하고 있는 문서 내용을 입력해 보세요. 이 가이드에 있는 기준에 따라 내용에 맞는 문서 유형과 작성 팁을 알려줘요. 자세한 원칙을 알고 싶다면 문서 유형 정하기를 살펴보세요.
# 역할
이 봇의 역할은 기술 문서를 작성하기 전에, 문서 유형과 각 유형에 맞는 작성법을 안내하는 것입니다.
아래 정보를 참고하여, 내 상황에 가장 적합한 문서 유형과 그 문서 유형에 맞는 작성 가이드를 추천해 주고. 필요하다면 복수의 문서 유형을 제안해도 괜찮지만, 최대한 하나로 정해주세요.
아래 정보를 바탕으로, 가장 적합한 문서 유형(학습 중심 / 문제 해결 / 참조 / 설명)과 작성 시 유의해야 할 점을 제안해 주세요.
이모지는 사용하지 마세요.
- 문서 목표 (예: "React의 Hook 개념을 자세히 알리고 싶다" / "Webpack 설정을 잡아주고 싶다" / "에러 발생 시 해결 방법을 제공하고 싶다" 등)
- 독자 수준 (예: "React를 처음 접하는 초급 개발자" / "이미 Webpack 사용 경험이 있는 중급 개발자" / "비개발자 포함" 등)
- 프로젝트 상황 (예: "새로운 기술을 도입해 보고 싶다" / "기존 프로젝트를 개선 중이라 빠른 해결이 필요하다" / "참조 문서가 너무 길어 핵심만 요약해야 한다" 등)
- 추가 고려 사항 (예: "짧은 시간 안에 완성해야 한다" / "시각 자료를 많이 활용하고 싶다" / "다양한 OS 환경을 고려해야 한다" 등)
위 정보를 종합해서, 내가 어떤 문서 유형을 쓰면 좋을지, 그리고 그 유형에 맞춰 작성할 때 주의해야 할 사항을 알려 주세요. 필요하다면 복수의 문서 유형을 제안해도 괜찮습니다.
...
문서 내용이 잘 구성되었는지 확인하거나 정보 구조를 개선하고 싶다면 Step 2. 정보 구조 만들기의 프롬프트를 사용해 보세요. 프롬프트를 적용한 봇에 내가 쓴 문서, 혹은 생각하고 있는 문서 내용을 입력해 보세요. 이 가이드에 있는 기준에 따라 개선할 부분을 알려줘요. 자세한 원칙을 알고 싶다면 정보 구조 만들기를 살펴보세요.
# 역할
이 봇의 역할은 기술 문서의 구조를 분석하고, 아래의 원칙들을 반영하여 문서를 개선할 수 있는 피드백과 개선안을 제안하는 것입니다.
아래 정보를 참고하여, 내가 작성한 문서 초안 혹은 문서 구조에 대해 피드백과 구체적인 개선안을 추천해 주세요.
여러 개선 옵션을 모두 반영한 하나의 좋은 안을 만들어 주세요.
...
효과적인 문장을 쓰고 싶거나, 내 문장을 다듬고 싶을 때는 Step 3. 문장 다듬기의 프롬프트를 사용해 보세요. 프롬프트를 적용한 봇에 내가 쓴 문서, 혹은 문장을 입력해 보세요. 이 가이드에 있는 기준에 따라 개선할 부분을 알려줘요. 자세한 원칙을 알고 싶다면 문장 다듬기를 살펴보세요.
# 역할
이 봇의 역할은 기술 문서의 문장을 효과적이고 간결하게 개선하는 것입니다. 아래 정보를 참고하여, 입력된 문장을 더 명확하고 이해하기 쉬운 문장으로 수정할 수 있도록 피드백과 개선안을 제안해 주세요.
여러 개선 옵션을 모두 반영한 하나의 좋은 안을 만들어 주세요.
...
기술 문서는 독자의 목적에 따라 문서 유형을 나눠볼 수 있어요. 이 유형을 알면 문서를 더 쉽게 작성할 수 있고, 독자도 필요한 정보를 빠르게 찾을 수 있어요.
여기에서는 문서를 크게 학습 중심 문서와 문제 해결 중심 문서, 참조 문서, 설명 문서 네 가지로 나누어 살펴볼게요.
| 문서 유형 | 독자의 목적 | 예시 |
|---|---|---|
| 학습 중심 문서 | 새로운 기술이나 도구를 처음 접해서 간단히 어떤 흐름인지 알고 싶을 때 사용해요. 초보자가 쉽게 시작할 수 있는 튜토리얼이나 사전 준비도 여기에 속해요. | use-funnel 시작하기 / Kotlin 시작하기 / MDN Web Docs - HTML 기본 / 토스페이먼츠 개발자센터 - 결제 연동하기 |
| 문제 해결 문서 | 배경 지식이 있는 상태에서 기술이나 도구를 사용하다 생기는 특정한 문제를 해결하고 싶을 때 사용해요. | Stripe Docs - Collect physical addresses / use-funnel - 퍼널 안에 퍼널 만들기 |
| 참조 문서 | 이미 기본적인 작동 방법을 알고 있는 상태에서 특정 기능이나 API 사용법을 확인해서 적용하고 싶을 때 사용해요. 특정 API 함수의 매개변수, 반환 값, 예제 코드 등을 확인하는 거에요. | es-toolkit 레퍼런스 / DevDocs JavaScript reference / MDN Web Docs - Reference |
| 설명 문서 | 개념, 원리, 배경 지식을 깊이 이해하고 싶을 때 사용해요. 예를 들어, 왜 이런 기술이 등장했는지, 어떤 문제를 해결하는지 등을 자세히 알고 싶을 때 사용해요. | MDN Web Docs - 웹의 동작 방식 |
이렇게 목표 중심으로 문서를 분류하고 선택하면, 독자가 필요로 하는 정보와 경험을 더 효과적으로 설계할 수 있어요.
좀 더 세분화 된 다음 의사결정 트리도 한 번 참고해 보세요.
하지만 이 분류가 항상 정답은 아니에요. 더 효과적인 문서를 만들기 위해 문서 유형을 결합해서 사용할 수도 있고, 다른 방식으로 분류할 수도 있어요. 예를 들어 JSON으로 작업하기 문서는 학습 중심 문서에 속하지만, 독자가 JSON에 대한 기본적인 지식부터 이해할 수 있도록 설명 문서의 요소와 결합되어 있어요.
학습을 위한 문서는 독자가 새로운 기술이나 도구를 배울 수 있도록 돕는 문서예요. 이 문서를 읽으면 읽는 사람이 무엇을 할 수 있는지에 대한 명확한 상을 제시할 수 있어야 해요.
- 독자가 따라하다가 막히거나 오류가 나면 안돼요. 마지막 단계까지 문제 없이 따라할 수 있도록 안정적인 학습 환경을 만들어 주세요.
- 모든 예제 코드는 실제로 실행해보고 검증했으며, 필요한 준비 사항도 꼼꼼히 안내해야 해요.
- 독자가 차근차근 진행할 수 있도록 구조를 만들어요.
- 예제도 간단한 것부터 점진적으로 난이도를 올리는 것이 좋습니다.
- 단순히 개념만 설명하는 것이 아니라, 실제 실행 가능한 예제 코드를 포함하세요. 예제는 핵심 기능을 잘 드러내야 하고, 독자가 직접 실행해보며 학습할 수 있도록 해야 합니다.
- 학습 문서에 실행할 수 있는 예제가 있는지 여부는 문서 경험을 향상시키는 주요 요소예요. 실제로 실행할 수 있는 코드가 있으면 코드 사용법에 대한 이해를 직관적으로 할 수 있고 바로 프로젝트에 가져다 쓰기도 편리하기 때문이에요.
예시를 보면서 학습을 위한 문서를 쓰는 법을 간단히 익혀봐요.
첫 번째 예시는 React 시작하기 문서예요.
# React 시작하기
React는 컴포넌트 기반으로 UI를 만들 수 있는 라이브러리예요. 여기서는 가장 기본적인 React 프로젝트를 실행해보고 동작 방식을 이해해요.
## React 실행하기
### 1️. 프로젝트 만들기
npx create-react-app my-app
cd my-app
npm start
개발 서버가 실행된 후, 브라우저에서 `http://localhost:3000`을 열어 React 기본 화면을 확인하세요.
## React에서 화면을 만드는 방법
React에서는 컴포넌트라는 개념을 사용해서 화면을 구성해요. 컴포넌트는 UI의 가장 작은 단위예요.
### 기본 컴포넌트 만들기
`src/App.js` 파일을 열고 내용을 아래처럼 바꿔보세요.
function App() {
return <h1>안녕하세요! React를 시작해 봅시다.</h1>;
}
export default App;
파일을 저장한 후, 브라우저를 새로고침하면 React 기본 화면 대신 "안녕하세요! React를 시작해 봅시다."라는 문구가 표시됩니다.
## 직접 컴포넌트 만들기
1. `src` 폴더 안에 `Welcome.js` 파일을 생성하세요.
2. 다음 코드를 입력하고 저장하세요.
function Welcome({ name }) {
return <h2>안녕하세요, {name}님!</h2>;
}
export default Welcome;
이제 `App.js`에서 새로운 `Welcome` 컴포넌트를 추가해보세요.
import Welcome from "./Welcome";
function App() {
return (
<div>
<h1>React 학습을 시작해봅시다!</h1>
<Welcome name="주연" />
</div>
);
}
export default App;- 필수 개념과 기본 사용법을 안내해요. 문서의 학습 목표를 명확히 제시해야 해요.
- 가장 기본적인 설치 및 기본 설정을 안내해요. 실행 후 결과를 확인하는 방법도 알려주세요.
- 사용자가 최소한의 코드로 바로 실행할 수 있도록 구성해요. 실행 결과를 확인하는 방법도 알려주세요. 각 단계를 잘 완료했을 때 기대할 수 있는 결과를 명확히 알려줘야 독자 스스로 각 단계를 성공했는지 확인할 수 있어요.
학습을 위한 문서에는 크게 두 가지 유형이 있어요. 시작하기와 튜토리얼이에요. 비슷하게 보이지만 조금 달라요.
- 시작하기 문서는 처음 접하는 독자가 주요 흐름 및 개념을 이해할 수 있도록 돕는 문서예요. 내용으로는 간단한 설치 및 설정 안내나 필수 흐름 및 개념이 소개되어야 하고, 전체적인 흐름을 이해할 수 있도록 구성해야 해요.
- 튜토리얼 문서는 명확한 목표와 결과물이 있어서 단순히 흐름을 익히는 시작하기보다 더 구체적이죠. 각 단계를 따라 하면서 자연스럽게 개념을 익히고, 코드를 실행하며 학습할 수 있도록 구성하는 것이 중요합니다.
- 하지만 이 분류는 엄격한 것은 아니에요. 만약 주요 흐름이나 개념, 설치와 설정이 아주 간단하다면 튜토리얼 문서의 초반에 포함되기도 해요.
학습을 위한 문서는 성공적인 학습 경험에 집중하는 문서라서 실제 프로젝트에서 발생하는 문제와는 거리가 멀어요. 또, 모든 정보를 한 문서에 담으려다 보면 복잡도가 높아지고 집중하기 어려워요. 이 문제를 어떻게 개선할 수 있을까요?
튜토리얼에는 가장 중요한 핵심 과정만 포함하고, 자주 발생하는 문제와 해결책을 문서 마지막에 FAQ 섹션으로 추가합니다. 이렇게 하면 튜토리얼 본문은 성공적인 학습 경험을 중심으로 유지하면서 동시에 독자가 부딪힐 수 있는 문제를 해결할 방법을 제공할 수 있어요.
튜토리얼 문서가 길어지면 독자가 핵심 내용을 빠르게 따라갈 수 있도록 일부 내용을 접어두는 방식이 유용할 수 있어요. 각 단계에서 발생할 수 있는 문제 뿐만 아니라 부가 설명, 추가 예제, 심화 개념을 숨겼다가 필요할 때 열어볼 수 있도록 제공할 수 있어요.
- 학습 목표를 명확하게 제시했나요?
- 직접 따라 해 봤을 때 오류가 생기지는 않나요?
- 단계별로 설명되어 있나요?
- 읽는 사람이 직접 실행 할 수 있는 코드 예제가 포함되어 있나요?
문제 해결을 위한 문서는 독자가 직면한 문제를 빠르고 효과적으로 해결할 수 있도록 돕는 문서예요.
이런 문서에서 가장 중요한 것은 이 문서를 보면 독자가 지금 겪고 있는 문제를 해결할 수 있는지 여부예요. 따라서 문제의 원인과 해결 방법을 논리적으로 제공하고, 바로 적용할 수 있는 해결책과 실용적인 예시를 제공해야 해요.
- 문제가 발생한 원인과 그로 인해 나타난 현상을 구분해서 설명하세요.
- 에러 메시지, 로그 예시를 포함하면 읽는 사람이 더 쉽게 문제를 이해할 수 있어요.
- 해결 방법은 명확하고 바로 적용할 수 있어야 해요.
- 코드 예제, 명령어, 설정 방법을 포함하세요.
- 해결책이 어떤 원리로 문제를 해결하는지도 언급하면 좋아요.
- 같은 문제가 다른 환경이나 설정에서 어떻게 나타날 수 있는지도 다뤄요. 예를 들어, OS나 라이브러리 버전에 따른 차이를 설명해 주세요.
문제 해결을 위한 문서 중 목표 달성을 위한 단계별 절차를 안내해서 읽는 사람이 특정 작업을 성공적으로 수행할 수 있도록 돕는 How-to 가이드를 어떻게 작성하는지 살펴볼게요.
How-to 가이드에는 단계별 실행 절차와 실행 가능한 코드 예제가 있어요. 튜토리얼과 달리 전체적인 흐름이나 개념을 이해하기 위한 것이 아니라 특정 작업을 성공적으로 수행하기 위한 문서예요.
# React에서 자동 재시도 기능 통합 가이드
1. 자동 재시도 로직을 React 컴포넌트에 통합하여 API 요청 실패 시 자동으로 재시도하는 기능을 구현하는 방법을 알려드려요.
이 기능으로 네트워크 불안정 상황에서도 안정적인 데이터 요청을 보장하여 사용자 경험을 개선할 수 있어요.
## UI 구현하기
2. 다음 예제는 자동 재시도 로직을 활용해 API 데이터를 불러오고, 로딩 상태와 오류 처리를 포함한 UI를 구현하는 코드입니다.
```jsx
import { useEffect, useState } from "react";
function App() {
const [data, setData] = useState(null);
const [error, setError] = useState(null);
const [loading, setLoading] = useState(true);
useEffect(() => {
fetchWithRetry("https://jsonplaceholder.typicode.com/todos/1", {}, 3, 1000)
.then(json => {
setData(json);
setLoading(false);
})
.catch(err => {
setError(err.message);
setLoading(false);
});
}, []);
return (
<div>
{loading ? (
<p>데이터 로딩 중...</p>
) : error ? (
<p style={{ color: "red" }}>{error}</p>
) : (
<div>
<h2>API 데이터</h2>
<pre>{JSON.stringify(data, null, 2)}</pre>
</div>
)}
</div>
);
}
export default App;- 이 문서의 목표와 타겟 독자를 명확히 정의했어요. 이 가이드는 '자동 재시도 기능 구현'이라는 구체적인 과제에 초점을 두고 있으며, 네트워크 불안정 상황에서도 안정적인 데이터 요청이 가능한 애플리케이션을 만드는 것이 최종 목표입니다. 독자는 이 문서를 통해 해당 기능의 구현 방법뿐만 아니라, 구현의 필요성과 효과에 대해서도 이해할 수 있습니다.
- 자동 재시도 로직(
fetchWithRetry)을 활용해 API 데이터를 안정적으로 요청하고 그 결과를 상태(state)에 반영하는 방법을 상세히 알려줘요.
트러블슈팅 문서에는 이미 발생한 문제를 진단하고 문제 해결을 위한 디버깅 과정에 중점을 둡니다.
# "Module not found: Can't resolve 'react'" 에러 해결 가이드
"Module not found: Can't resolve 'react'" 에러가 발생했을 때 해결 방법을 알려드려요.
## 1. 패키지 설치 여부 확인
이 에러는 React 패키지가 설치되어 있지 않거나, `node_modules` 디렉토리 내에 해당 모듈이 존재하지 않을 때 발생합니다.
터미널에서 아래 명령어를 실행하여 React 패키지가 설치되어 있는지 확인하세요.
```bash
npm list react문제가 계속된다면, React 및 React-DOM 패키지를 재설치해 보세요.
node_modules 디렉토리와 package-lock.json 파일을 삭제한 후 다시 설치하면, 환경 관련 문제가 해결될 가능성이 높습니다.
# React 및 React-DOM 재설치
npm install react react-dom
# 또는, 재설치 절차:
rm -rf node_modules package-lock.json
npm install
# 이후 프로젝트 실행
npm startNode.js 버전이 호환되지 않는 경우에도 이 에러가 발생할 수 있어요. 현재 Node.js 버전을 확인하고, 필요하다면 호환되는 버전으로 전환하세요.
node -v
nvm use 18
- 첫 번째 단계에서 문제의 가장 기본적인 원인을 신속하게 진단할 수 있도록 안내해서 빠르게 문제를 해결할 수 있도록 도와줘요.
- 다른 해결 방법도 제안해서 해결 가능성을 높여요. 또, `npm start`를 실행하는 단계를 포함하여 최종적으로 문제가 해결되었는지 확인할 수 있도록 구성했어요.
#### How-to 가이드와 트러블슈팅 문서의 차이점
- **가이드 문서**는 특정 기능 구현에 초점을 맞춘 문서이고,
- **트러블슈팅 문서**는 이미 발생한 문제를 진단하고 문제 해결을 위한 디버깅 과정에 중점을 둡니다.
## 체크리스트
- [ ] 단순히 에러 원인만 설명하는 게 아니라, 에러에 대한 기본적인 지식도 충분히 제공했나요?
- [ ] 즉시 적용할 수 있는 해결 방법이 포함되어 있나요?
- [ ] 환경별(운영체제, 라이브러리 버전 등) 차이를 고려한 설명도 포함되어 있나요?
# 참조를 위한 문서 📑
참조 문서는 독자가 특정 기술, 도구, 또는 시스템에 대한 정확하고 완전한 정보를 빠르게 찾을 수 있도록 설계된 문서예요. 핵심은 정확성, 완전성, 검색 용이성이며, 독자가 필요할 때 즉시 원하는 정보를 찾아 적용할 수 있어야 해요.
또 함수, 매개변수, 반환값, 사용 예제 같은 구성을 정하고 일관되게 작성해야 해요.
### 1. 정확성과 완전성이 중요해요
문서에 포함된 모든 정보는 정확해야 하고, 누락된 부분이 없어야 해요. 기술적 오류나 모호한 설명이 없어야 하며, 항상 최신 상태여야 해요.
### 2. 일관된 구조로 작성해요
일관된 포맷과 구조로 가독성을 높여야 해요. API 문서라면 함수 이름 → 매개변수 → 반환값 → 예제 코드 순과 같은 표준화된 구조를 만들어요.
### 3. 검색과 탐색이 쉬워요
독자가 필요한 정보를 빠르게 찾을 수 있도록 문서를 체계적으로 구성해야 해요. 목차, 키워드 검색, 앵커 링크 등을 활용해서 정보를 쉽게 탐색할 수 있도록 해야 해요.
### 4. 예제 코드를 제공해요
명확한 설명과 함께 예제 코드를 함께 제공해야 해요. 예제 코드로 특정 함수나 API를 어떻게 사용하는지 직관적으로 알 수 있어요.
## 이해하기
API 문서 예시를 보면서 참조 문서 쓰는 법을 간단히 익혀봐요.
```markdown
# `fetch` API
`fetch` 함수는 네트워크 리소스를 요청하고 응답을 처리하는 API예요. 비동기적으로 동작하고, `Promise<Response>` 객체를 반환해요. `fetch` 함수를 활용하면 클라이언트와 서버 간 데이터를 쉽게 주고받을 수 있어, REST API와 같은 서비스와의 통신을 효율적으로 처리할 수 있어요.
`XMLHttpRequest`보다 간결한 문법을 제공하고, `async/await`와 함께 사용하면 가독성이 뛰어나다는 장점도 있어요.
## 시그니처
```typescript
fetch(input: RequestInfo, init?: RequestInit): Promise<Response>
input(필수): 요청할 URL 또는Request객체예요.init(선택): 요청의 옵션을 담은 객체예요.method: HTTP 요청 방식 (GET, POST, PUT, DELETE 등)headers: 요청에 포함할 헤더 정보 (예: { 'Content-Type': 'application/json' })body: 요청 본문 (예: JSON.stringify({ name: 'John' }))mode: 요청 모드 (cors, no-cors, same-origin)credentials: 쿠키 포함 여부 (omit, same-origin, include)cache: 캐시 정책 (default, no-store, reload, force-cache 등)redirect: 리디렉션 처리 방식 (follow, error, manual)
fetch는 Promise<Response> 객체를 반환해요.
ok: 응답이 성공(200~299)했는지 여부 (true / false)status: HTTP 상태 코드 (200, 404, 500 등)headers: 응답 헤더 (Headers 객체)json(): 응답을 JSON으로 변환 (Promise)text(): 응답을 문자열로 변환 (Promise)blob(): 응답을 Blob 객체로 변환 (Promise)
fetch('https://jsonplaceholder.typicode.com/posts/1')
.then(response => {
if (!response.ok) {
throw new Error('네트워크 응답이 올바르지 않아요.');
}
return response.json();
})
.then(data => console.log(data))
.catch(error => console.error('오류 발생:', error));fetch('https://api.example.com/user', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({ name: 'John', age: 30 }),
})
.then(response => {
if (!response.ok) {
throw new Error('요청이 실패했어요.');
}
return response.json();
})
.then(data => console.log('서버 응답:', data))
.catch(error => console.error('오류 발생:', error));async function fetchData() {
try {
const response = await fetch('https://jsonplaceholder.typicode.com/posts/1');
if (!response.ok) {
throw new Error('네트워크 응답이 올바르지 않아요.');
}
const data = await response.json();
console.log(data);
} catch (error) {
console.error('오류 발생:', error);
}
}
fetchData();
- fetch 함수에 대해 간단히 설명해요. 기능 뿐만 아니라 이 함수가 제공하는 가치를 설명해요.
- 함수의 시그니처를 설명해요. 시그니처를 작성하면 함수의 입력값과 반환값을 직관적으로 파악할 수 있어요. 이를 통해 개발자는 함수의 동작 방식을 빠르게 이해하고, 올바른 매개변수를 전달할 수 있어요.
- fetch 함수의 매개변수와 반환값을 정리해요. Response 객체의 주요 속성을 나열하고, 반환값을 다루는 방법을 쉽게 이해할 수 있도록 했습니다.
- 기본적인 사용 예제를 제공해요. fetch를 활용하여 데이터를 가져오는 방법과 오류 처리를 함께 설명했습니다.
- 기본 예제 뿐 아니라 독자가 활용할 수 있도록 추가로 참고할만한 코드 예제도 추가할 수 있어요.
## 더 나아가기
참조 문서는 방대한 양의 정보를 포함하기 때문에 독자가 원하는 내용을 빠르게 찾기 어려울 수 있어요. 이를 해결하기 위해 주제별로 섹션을 나누고 목차를 제공하면 탐색이 쉬워져요. [예시 문서](https://docs.tosspayments.com/reference#%EA%B2%B0%EC%A0%9C)를 보면 결제라는 도메인을 주제별로 나누고 오른쪽에 API별 목차를 제공하고 있어요.
또, 독자가 참조 문서를 활용하기 전에 반드시 알아야 할 정보의 배치도 신경쓰면 좋아요. 독자가 항상 참조 문서를 활용하는 시점에만 문서를 보는 게 아니기 때문에 사전에 알아야 할 정보가 있을 수 있어요. 예를 들면 API 키 설정, 인증 방식, 요청 헤더 구성 같은 핵심 정보를 문서의 앞부분에 두어 눈에 잘 띄도록 하면 좋아요. 덕분에 독자가 문서를 처음 접했을 때 필요한 내용을 놓치지 않을 수 있었어요.
## 체크리스트
- [ ] 검색 및 탐색이 쉬운 구조인가요?
- [ ] 정보가 정확하고 완전한가요?
- [ ] 문서가 일관된 구조와 형식으로 작성되어 있나요?
- [ ] 실용적인 예시 코드가 포함되어 있나요?
# 깊은 이해를 위한 문서 🔍
깊은 이해를 위한 설명 문서는 독자가 특정 기술이나 개념을 깊이 있게 이해할 수 있도록 돕는 것을 목표로 해요. 핵심은 배경과 맥락을 충분히 설명하고, 의사결정 과정을 명확히 공유하는 것이에요.
이 문서를 보면 독자는 단순한 사용법을 넘어 기술의 원리와 철학을 이해할 수 있어야 해요.
### 1. 배경 및 맥락을 제공해요
- 기술이 등장한 이유와 해결하려는 문제를 먼저 설명해요.
- 독자가 해당 기술을 왜 선택해야 하는지 납득할 수 있도록 설득력 있게 서술해요.
### 2. 시각 자료를 적극적으로 활용해요
- 복잡한 개념은 다이어그램, 흐름도, 표 등을 사용해 시각화해요.
- 전체적인 구조, 데이터 흐름이나 컴포넌트 구조는 시각적으로 보여주면 더 직관적으로 이해할 수 있어요.
## 이해하기
개념 이해를 위한 문서와 도메인 지식을 다루는 문서 두 가지를 예시로 살펴보며 이해할게요.
### 1. 개념 이해를 위한 문서 예시
특정 개념의 원리와 작동 방식을 설명하는 문서는 기본적인 원리부터 응용까지 다루며, 독자가 개념을 깊이 이해하도록 돕는 것이 핵심이에요.
첫 번째 예시는 React의 가상 DOM 작동 원리를 설명하는 문서예요.
```markdown
# React의 가상 DOM 작동 원리
React의 가상 DOM(Virtual DOM)은 UI 변경을 효율적으로 감지하고 최소한의 변경만 실제 DOM에 반영하는 방식을 통해 성능을 최적화하는 핵심 기술입니다. 이를 통해 불필요한 렌더링을 방지하고 빠른 UI 업데이트를 제공합니다.
## 가상 DOM이 등장한 배경
웹 애플리케이션이 복잡해지면서, 기존의 DOM 조작 방식에는 다음과 같은 문제가 발생했습니다.
- DOM 조작 비용이 크다: 직접적인 DOM 변경이 많아질수록 브라우저의 렌더링 성능이 저하됩니다.
- 전체 페이지 리렌더링 문제: 특정 부분만 변경해도 전체 UI가 다시 그려지는 경우가 많습니다.
- UI 성능 저하: 많은 DOM 업데이트가 발생하면 프레임 속도가 떨어지고 사용자 경험(UX)이 저하될 가능성이 높습니다.
React는 이러한 문제를 해결하기 위해 가상 DOM을 도입했습니다. 가상 DOM을 활용하면 변경 사항을 먼저 계산하고, 최소한의 연산으로 실제 DOM을 업데이트할 수 있습니다.
## 개념
가상 DOM(Virtual DOM)은 실제 DOM의 경량화된 JavaScript 객체 모델입니다. React는 UI 변경이 발생하면 이 가상 DOM을 업데이트한 후, 변경된 부분만 실제 DOM에 반영합니다.
이 방식의 장점은 다음과 같습니다:
- 빠른 연산 가능: 가상 DOM은 메모리에서 동작하므로 계산 속도가 빠릅니다.
- 효율적인 업데이트: 변경 사항을 비교하여 최소한의 DOM 업데이트만 수행합니다.
- 예측 가능성 향상: 선언적 UI 모델을 유지하면서도 최적화된 성능을 제공합니다.
### 작동 방식
가상 DOM은 다음과 같은 과정을 거쳐 렌더링을 최적화해요.
1. UI 변경 감지: React는 컴포넌트의 상태(state)나 속성(props)이 변경되면 새로운 가상 DOM을 생성합니다.
2. Diffing 알고리즘 적용: 이전 가상 DOM과 새로운 가상 DOM을 비교하여 변경된 요소를 찾습니다.
3. 최소한의 변경만 반영: 변경된 부분만 실제 DOM에 적용하여 성능을 최적화합니다.
이 과정은 React의 핵심 알고리즘인 Reconciliation(조정 과정)을 기반으로 작동합니다.
## 시각적 다이어그램
다음 다이어그램은 가상 DOM의 작동 과정을 나타내요.
🖥️ UI 변경 감지
┌─────────────────────────────────┐
│ UI 변경 감지 │
│ (컴포넌트의 상태/props 변경 감지) │
└─────────────────────────────────┘
│
▼
⚙️ 가상 DOM 업데이트
┌─────────────────────────────────┐
│ 가상 DOM 생성 및 업데이트 │
└─────────────────────────────────┘
│
▼
🔍 Diffing 알고리즘 적용
┌─────────────────────────────────┐
│ 이전 가상 DOM과 비교하여 │
│ 변경된 요소 도출 │
└─────────────────────────────────┘
│
▼
💻 최소 변경 반영 (실제 DOM)
┌─────────────────────────────────┐
│ 변경된 부분만 실제 DOM에 반영 │
└─────────────────────────────────┘
위 과정에서 가장 중요한 것은 Diffing 알고리즘입니다. React는 `key` 속성을 활용하여 변경된 노드를 빠르게 찾고, 효율적으로 업데이트할 수 있도록 설계되어 있습니다.
## 코드 예제
React의 가상 DOM을 활용하는 간단한 예제입니다.
```javascript
import React, { useState } from 'react';
function Counter() {
const [count, setCount] = useState(0);
return (
<div>
<p>현재 카운트: {count}</p>
<button onClick={() => setCount(count + 1)}>증가</button>
</div>
);
}
export default Counter;
이 코드에서 setCount를 호출하면 React는 새로운 가상 DOM을 생성하고, 이전 상태와 비교하여 변경된 부분만 실제 DOM에 반영합니다.
가상 DOM은 Redux나 MobX 같은 상태 관리 라이브러리와 함께 사용하면 더욱 강력한 성능을 발휘할 수 있습니다. 이러한 라이브러리는 상태(state) 변경을 추적하고, 변경된 데이터를 기반으로 UI를 효율적으로 업데이트하는 역할을 합니다.
- 가상 DOM의 개념과 필요성을 명확히 설명해요. 가상 DOM의 개념과 기존 DOM 조작의 문제점을 명확히 짚어주고, 가상 DOM이 이를 어떻게 해결하는지 알려줘요.
- 가상 DOM의 작동 방식을 논리적으로 정리해요. 단계별로 핵심 원리를 알려주고, 각 과정이 어떤 역할을 하는지 쉽게 이해할 수 있도록 했어요.
- 시각적 자료를 활용해 추상적인 개념을 좀 더 잘 이해할 수 있도록 보완해요.
### 2. 도메인 문서 예시
다음은 특정 도메인에 대한 이해를 돕는 문서예요. 독자가 도메인을 깊이 이해할 수 있도록 돕는 것이 핵심이에요.
예시를 참고해서 내 서비스가 다루는 도메인(예: 커머스, 금융, 소셜 미디어 등)에 대한 문서를 작성해 보세요.
```markdown
# 커머스 도메인 이해하기
이 문서는 커머스 도메인의 개념과 흐름을 설명해요.
커머스 도메인은 전자상거래 시스템에서 상품 판매, 주문 처리, 결제, 배송 등 거래 과정을 다루는 핵심 개념이에요.
효율적인 커머스 시스템을 구축하려면 도메인의 구조와 주요 요소를 이해하는 것이 중요해요.
## 1. 기본 개념
커머스 도메인은 다음과 같은 핵심 요소로 구성돼요.
- 상품(Product): 판매하는 물품이나 서비스
- 주문(Order): 소비자가 상품을 구매하는 행위
- 결제(Payment): 거래 대금을 처리하는 과정
- 배송(Shipping): 상품을 소비자에게 전달하는 절차
- 소비자(Consumer): 상품이나 서비스를 구매하는 사람
- 판매자(Seller): 상품이나 서비스를 제공하는 사람
이 요소들은 서로 긴밀하게 연결되어 있어요. 예를 들어, 주문(Order)이 생성되면 결제(Payment)가 진행되고, 결제가 완료되면 배송(Shipping) 절차가 시작돼요.
## 2. 유저 행동 흐름
소비자가 상품을 구매할 때의 주요 과정은 다음과 같아요.
1. 상품 탐색 및 장바구니 추가: 소비자는 원하는 상품을 선택하고 장바구니에 추가해요.
2. 주문 및 결제 진행: 장바구니에서 주문을 확정하고 결제를 진행해요.
3. 결제 승인 및 주문 확정: 결제가 승인되면 주문이 확정돼요.
4. 배송 준비 및 출고: 판매자가 주문을 확인하고 상품을 포장한 후 출고해요.
5. 소비자에게 상품 도착: 택배 또는 다른 배송 수단을 통해 소비자에게 상품이 전달돼요.
이 과정에서 결제 승인 오류, 재고 부족, 배송 지연 등의 예외 상황이 발생할 수 있어요. 개발자는 이런 예외 처리를 고려해 로직을 설계해야 해요.
## 3. 도메인 흐름도
아래 흐름도는 커머스 도메인의 주요 요소들이 어떻게 연결되는지 보여줘요.
🛍️ 소비자 (Consumer)
│
┌─────────────┴─────────────┐
▼ ▼
┌───────────────┐ ┌───────────────┐
│ 장바구니 (Cart) │ ──▶ │ 주문 (Order) │
└───────────────┘ └───────────────┘
│ │
▼ ▼
┌───────────────┐ ┌───────────────┐
│ 상품 (Product) │ │ 결제 (Payment) │
└───────────────┘ └───────────────┘
│ │
▼ ▼
┌───────────────┐ ┌───────────────┐
│재고 (Inventory)│ │ 배송 (Shipping)│
└───────────────┘ └───────────────┘
│
▼
┌───────────────┐
│ 판매자 (Seller) │
└───────────────┘
- 커머스 도메인의 개념과 역할을 설명해요. 도메인이 포함하는 주요 거래 요소를 정의하고, 전자상거래 시스템에서의 중요성을 강조했어요.
- 커머스 도메인의 핵심 요소를 정리했어요. 상품, 주문, 결제, 배송 등의 개념을 설명하고, 각 요소가 어떻게 연결되는지 간단히 흐름을 알려줘요.
- 사용자의 구매 프로세스를 단계별로 정리했어요. 각 단계에서 발생할 수 있는 예외 상황(예: 결제 오류, 배송 지연 등)도 언급해서 개발자가 고려해야 할 사항을 알 수 있게 했어요.
- 커머스 도메인의 전체 흐름을 다이어그램으로 표현했어요. 시각적 자료를 활용하여 도메인 내 요소들이 어떻게 연결되는지 한눈에 이해할 수 있도록 했어요.
- 핵심 원리와 배경이 명확하게 설명되었나요?
- 복잡한 개념을 시각화하여 설명했나요?
- 선행 지식이 충분히 안내되었나요?
문서를 작성하는 사람이 알고 있어야 할 가장 기본이 되는 원칙과 문서 구조를 짜는 방법, 그리고 각 구조를 어떻게 효과적으로 작성할 수 있을지 소개할게요.
가장 중요한 건 문서를 읽는 사람 입장에서 설계하는 거예요. 기술 문서는 주로 문제 해결, 학습, 참조 목적으로 사용되기 때문에 독자가 어떤 목표를 가지고 문서를 찾았을지 고려하면서 작성해야 해요.
- 제목 깊이가
####(H4) 이상이 되면 문서를 나누는 것을 고려하세요. - 개요를 다루는 페이지를 활용해 보세요.
- 최대한 구체적인 주제를 다루세요.
- 부가적인 정보나 세부 사항은 나중에 배치하세요.
- 기능 중심 설명을 피하고, 독자가 얻을 가치를 먼저 전달하세요.
- 제목에는 핵심 키워드를 포함하세요.
- 일관성을 유지하세요.
- 제목은 30자 이내로 간결하게 쓰세요.
- 제목은 평서문으로 작성하세요.
- 개요는 문서의 핵심 내용을 요약해야 합니다.
- 문서의 목표를 독자에게 명확히 전달하세요.
- 기술적 배경 설명보다는 핵심 정보를 먼저 제공하세요.
- 일관된 제목, 형식, 구조를 유지하세요.
- 섹션 제목은 동일한 패턴을 따르세요.
- 논리적인 순서로 정보를 배치하세요.
- 용어를 일관되게 사용하세요.
문서를 작성할 때 한 페이지에서 하나의 핵심 목표만 다루는 것이 중요해요. 한 문서에서 너무 많은 내용을 담으면 독자가 핵심을 파악하기 어려워지고, 필요한 정보를 빠르게 찾기 어려워질 수 있어요.
문서가 너무 길어지거나 한 페이지에 여러 개념이 뒤섞이면 독자가 원하는 정보를 찾기가 어려워요. 각 문서가 하나의 주제에 집중한다면, 독자는 원하는 정보를 더 빠르고 쉽게 탐색할 수 있어요.
하나의 문서에서 너무 많은 내용을 다루면 추후 업데이트가 어려워질 수 있어요. 특정 개념이 변경될 때 관련 내용을 찾아 수정하는 것이 어려워지고, 중복된 내용이 여러 문서에서 발생할 수도 있어요.
제목의 위계가 4단계(####, H4) 이상으로 깊어진다면, 그 문서는 여러 개의 문서로 나누어야 할 신호예요. 문서의 계층 구조가 너무 복잡해지면, 독자가 문서의 흐름을 이해하기 어려워지고 정보를 빠르게 스캔하기가 어려워져요.
### (H3)까지는 유지할 수 있지만, #### (H4)부터는 문서가 지나치게 깊어졌다는 신호예요. 이럴 때는 하위 개념을 별도의 문서로 분리하는 것이 가독성과 탐색성을 높여보세요.
이 문서는 "React 사용법"라는 너무 넓은 주제를 다루고 있어요. 한 페이지에서 너무 많은 개념을 한꺼번에 설명하면, 독자가 원하는 정보를 찾기가 어려워져요. H4(####), H5(#####)와 같은 깊은 제목이 등장하면 문서를 분리해야 할 신호예요.
# React 사용법
## 컴포넌트 생성
### 컴포넌트 기본 구조
#### JSX 사용법
##### JSX 문법 세부사항
## 상태 관리
### 상태 정의
#### useState 사용법이 페이지에서는 'React 컴포넌트 생성'이라는 하나의 목표만 다루고 있어요. 컴포넌트 생성과 관련된 주요 내용을 다루지만, 개별적인 개념을 한 페이지에서 지나치게 세부적으로 파고들지는 않아요.
# React 컴포넌트 생성하기
## 컴포넌트 기본 구조
## 상태 관리
## 라이프사이클 메서드여러 개념을 개략적으로 소개해야 한다면, 개별 문서로 연결되는 개요 페이지를 따로 만드는 것이 좋아요. 예를 들어, "React 기본 개념" 문서에서 "컴포넌트", "상태 관리", "라이프사이클"에 대한 개요를 제공하고, 각 항목을 별도의 문서로 연결하는 방식이 효과적이에요.
한 페이지에서 두 개 이상의 핵심 주제를 다루고 있다면 문서를 분리하세요.
기능 중심의 설명보다는 독자가 얻을 수 있는 가치를 먼저 설명하는 것이 좋아요. 독자가 문서를 읽고 어떤 문제를 해결할 수 있는지, 어떤 긍정적인 변화를 기대할 수 있는지 먼저 전달해야 해요.
문서를 작성할 때 많은 사람이 기능이나 세부 설정을 먼저 설명하려는 실수를 해요. 문서를 작성하는 사람 입장에서 생각하기 때문이에요.
독자는 "이 기능이 왜 필요한가?", "내게 어떤 도움이 되는가?"를 먼저 알고 싶어 해요. 따라서 기능 설명보다 먼저, 이 기능이 해결하는 문제와 제공하는 가치를 먼저 전달하는 것이 중요해요.
독자는 자신이 해결하고 싶은 문제가 해결될지 궁금해하며 문서를 읽어요. 가장 먼저 이 문서를 읽으면 무엇을 얻을 수 있는지, 어떤 문제를 해결할 수 있는지를 명확하게 전달하면, 독자가 내용을 끝까지 읽을 가능성이 높아져요.
독자가 이 문서를 읽고 해결할 수 있는 문제나 독자가 기대할 수 있는 긍정적인 변화를 먼저 설명하세요.
"리버스 프록시 설정은 2019년에 도입되었고, 많은 수정이 있었습니다..."
- 독자에게 가장 중요한 정보가 아니라 배경 지식부터 설명하고 있어요.
"리버스 프록시 설정을 적용하면 네트워크 지연 문제를 최소화할 수 있어요."
- 먼저 적용했을 때 얻을 수 있는 가치를 전달하고 있어요.
기능 나열보다 이 기능이 왜 유용한지를 먼저 설명하세요. 예를 들면 "이 API는 여러 설정 옵션을 제공합니다." 보다는 "이 API를 사용하면 로그 데이터를 실시간으로 처리할 수 있습니다." 가 독자에게 더 유용해요.
"이 스니펫은 다양한 설정 옵션을 제공합니다. 먼저 connection_timeout, retry_attempts, max_pool_size 등의 매개변수를 수정하세요. 그런 다음, ..."
- 독자가 얻을 수 있는 핵심 가치를 설명하지 않고, 세부 설정부터 나열하고 있어요.
"이 스니펫을 사용하면 PostgreSQL 데이터베이스 연결 속도가 50% 빨라집니다."
- 독자가 기대할 수 있는 긍정적인 변화를 먼저 설명하고 있어요.
제목은 문서의 핵심 내용을 간결하고 명확하게 전달해야 합니다. 독자가 문서를 스캔하면서 빠르게 내용을 파악할 수 있도록, 명확하고 검색하기 쉬운 제목을 작성하는 것이 중요합니다.
제목이 명확하고 간결하면 독자가 문서를 빠르게 스캔할 수 있습니다. 문서의 주제를 한눈에 파악할 수 있도록 제목을 직관적으로 작성해야 합니다.
제목에 핵심 키워드가 포함되면 검색 엔진에서 문서를 찾기 쉬워집니다. 또한, 문서 내에서도 독자가 원하는 정보를 빠르게 찾을 수 있습니다.
제목의 스타일이 일관되면 문서가 더 체계적으로 보이며, 독자가 다른 문서와의 관계를 쉽게 이해할 수 있습니다.
문서의 주요 내용을 빠르게 전달할 수 있도록, 독자가 검색할 가능성이 높은 핵심 키워드를 넣어요.
# 에러를 해결하는 방법은?- 제목만으로 내용을 즉시 이해하기 어렵습니다.
- "이 문서가 무엇을 말하려는 걸까?"라고 추측해야 합니다.
# `NOT_FOUND_USER` 에러를 해결하는 방법- 제목 자체만으로 문서의 목적을 명확하게 전달하고 있습니다.
문서 전체에서 제목의 스타일을 일관되게 유지하세요. 같은 수준의 소제목은 동일한 문체와 표현 방식을 따라야 합니다. 제목을 동사형 또는 명사형으로 통일하세요.
단계가 있다면 숫자를 사용하세요. 단계별 절차를 다루는 문서라면, 제목에 숫자를 포함하면 이해하기 쉽습니다.
# 제목을 쓰는 방법
## 키워드를 포함하세요
## 일관성 유지
## 평서문으로 작성하기- 소제목 스타일에 일관성이 없어요.
# 제목을 쓰는 방법
## 키워드 포함하기
## 일관성 유지하기
## 평서문으로 작성하기- 일관된 '~하기' 제목을 사용했어요.
중복되거나 불필요한 단어를 줄이고, 핵심 정보만 남겨서 가독성을 높여요.
느낌표(!)나 물음표(?) 대신 평서문을 사용하세요. 느낌표나 물음표는 감정을 강조하거나 독자의 관심을 끄는 역할을 할 수 있지만, 기술 문서에서는 문서의 주제와 목적을 빠르게 이해하는 것이 더 중요합니다.
개요는 문서의 핵심 내용을 요약하고, 독자가 문서를 읽기 전에 내용을 빠르게 이해할 수 있도록 돕습니다. 명확한 개요는 독자가 문서를 끝까지 읽을지 결정하는 중요한 요소이며, 문서의 흐름을 효과적으로 전달하는 역할을 합니다.
적절한 개요는 독자가 문서의 핵심 내용을 파악하고, 필요한 정보를 찾는 시간을 줄여줍니다. 문서의 개요를 읽는 것만으로 문서가 다루는 주제와 목적을 이해할 수 있어야 합니다.
검색 엔진이나 문서 시스템에서 개요는 검색 결과의 일부로 표시될 때가 많습니다. 개요가 잘 작성된 문서는 검색 결과에서 더 많은 클릭을 유도할 수 있습니다.
개요를 먼저 작성하면, 문서의 주요 논점을 정리하고 불필요한 내용을 줄여서 문서의 초점을 유지하는 데 도움이 됩니다.
문서 전체를 읽지 않아도, 개요만으로 문서의 주제를 파악할 수 있어야 해요. 개요는 제목 바로 아래, 본문이 시작되기 전에 배치하세요.
"이 문서를 읽으면 무엇을 할 수 있는가?"에 대한 답을 개요에서 제공하세요.
TypeScript의 유틸리티 타입 이 문서는 TypeScript의 유틸리티 타입을 소개합니다. Partial, Pick, Omit 등의 유틸리티 타입을 사용할 수 있어요.
- "왜 유틸리티 타입을 사용해야 하는지"에 대한 설명이 부족합니다.
TypeScript의 유틸리티 타입 TypeScript의 유틸리티 타입을 사용해서 객체 타입을 변형하는 방법을 알아볼게요. 유틸리티 타입을 활용하면 반복적인 타입 선언을 줄이고, 더 유연하게 타입을 관리할 수 있어요. 이 문서에서는 Partial, Pick, Omit 등을 사용하여 객체 타입을 효과적으로 다루는 방법을 알아볼게요.
- 독자가 문서를 통해 배울 수 있는 내용을 명확하게 설명하고 있습니다.
기능에 대한 상세한 설명을 바로 넣기 보다는, 독자가 해당 기능으로 얻을 수 있는 직접적인 가치를 먼저 알려주세요.
React 상태 관리 React에서 상태 관리란 무엇일까요? React는 컴포넌트 기반 UI 라이브러리로, 상태(state)를 관리하는 것이 중요합니다. 상태 관리는 여러 방식으로 구현할 수 있으며, 다양한 라이브러리도 존재합니다. 이 문서에서는 상태 관리의 개념과 몇 가지 방법을 소개합니다.
- 개요가 너무 길고 설명이 추상적이라서 핵심 내용을 파악하기 어렵습니다.
React 상태 관리
이 문서는 React에서 상태(state) 관리의 개념과 주요 기법을 설명합니다.
useState, useReducer, Context API, Redux 등의 방법을 비교하고, 각 방식의 장점과 단점을 이해할 수 있도록 안내합니다.
- 개요만 읽어도 문서의 핵심 내용을 쉽게 파악할 수 있습니다.
문서는 독자가 쉽게 탐색하고 필요한 정보를 빠르게 찾을 수 있도록 예측 가능해야 합니다. 예측 가능한 문서 구조는 독자가 내용을 이해하는 데 드는 인지 부담을 줄이고, 문서를 효율적으로 활용할 수 있도록 돕습니다.
예측 가능한 문서는 일관된 용어와 표현을 사용하고, 설명의 흐름이 자연스럽게 연결되며, 새로운 정보가 논리적인 순서로 배치됩니다.
문서가 일관된 구조를 가지면, 독자는 필요한 정보를 쉽게 찾을 수 있습니다. 예측 가능성이 낮으면 독자는 어디에서 원하는 내용을 찾아야 할지 혼란스러워질 수 있습니다.
일관된 제목, 형식, 문단 구조를 유지하면, 새로운 문서를 접할 때도 기존 문서의 흐름을 연장해서 이해할 수 있습니다. 특히 문서가 많아질수록 예측 가능성이 더욱 중요합니다.
예측 가능한 문서 구조는 팀 내에서 문서를 유지보수할 때도 큰 도움이 됩니다. 일관된 패턴을 따르면 어떤 정보를 어디에 위치시켜야 하는지 쉽게 결정할 수 있습니다.
Don't
# API 요청 최적화
이 문서에서는 API 요청을 최적화하는 여러 가지 방법을 설명합니다.
## 성능 향상 기법
- 캐싱 활용하기
- 요청 병합하기
### API 속도 측정
API 응답 속도를 분석하는 방법을 설명합니다.
## 오류 처리
API 요청 중 발생할 수 있는 문제와 해결책을 설명합니다.- 섹션 간의 위계가 불규칙하고, 각 내용이 어떻게 연결되는지 명확하지 않습니다.
Do
# API 요청 최적화
API 요청을 줄이고 성능을 향상시키는 방법을 알아봅니다.
## 1. 성능 향상 기법
### 캐싱 활용하기
### 요청 병합하기
## 2. API 속도 측정
API 응답 속도를 분석하는 방법을 설명합니다.
## 3. 오류 처리
API 요청 중 발생할 수 있는 문제와 해결책을 설명합니다.- 같은 수준의 개념을 일관된 위계로 정리하여 예측 가능성을 높였습니다.
- 같은 수준의 개념은 같은 제목 깊이(H2, H3 등)로 작성하세요.
- 제목에 일관된 키워드와 표현을 사용하세요.
- 기본 개념 → 상세 설명 → 예시/활용 순으로 정보를 배열하면 독자가 자연스럽게 따라올 수 있습니다.
- 같은 개념에는 항상 같은 용어를 사용해 혼란을 줄이세요.
기술 문서는 명확하고 이해하기 쉬워야 합니다. 이 가이드는 효과적인 문장을 쓰기 위한 핵심 원칙들을 제안해요.
- 도구나 기술, 시스템을 행동의 주체로 사용하지 않아요.
- 능동형으로 표현해요.
- 문장을 짧고 간결하게 유지하세요.
- 메타 담화를 최소화하세요.
- 명사 대신 동사를 사용하세요.
- 모호한 표현 대신 명확한 표현을 사용하세요.
- 불필요한 한자어를 제거하세요.
- 번역체 표현을 자연스럽게 수정하세요.
- 공식 기술 용어를 따르세요.
- 같은 개념을 여러 방식으로 표현하지 마세요.
- 약어는 먼저 풀어쓴 후 사용하세요.
- 외래어 표기는 사용 빈도를 고려하세요.
기술 문서를 읽는 독자는 주로 개발자예요. 또, 개발 문서에 적힌 작업을 직접 하는 것도 개발자죠. 따라서 기술 문서에서는 문서를 읽는 사람이 곧 행동의 주체예요. 명시적으로 드러내지 않더라도, 문맥에서 개발자가 주체임을 고려하면 더 자연스럽고 명확한 문장이 돼요.
문서에서 설명하는 목표와 작업을 수행하는 사람은 개발자예요. 그래서 도구나 기술 자체를 문장의 주어로 사용하면 어색할 때가 있어요. 이 문서를 읽고 개발자가 할 수 있는 일을 중심으로 설명해 보세요.
- 이 라이브러리는 데이터베이스 초기화를 수행해요.
- 이 코드는 API 요청으로 인증 토큰을 추가해요.
- 이 명령어를 실행하면 데이터베이스를 초기화할 수 있어요.
- 이 코드를 사용하면, API를 요청했을 때 자동으로 인증 토큰을 추가할 수 있어요.
다만, 도구나 기술의 동작을 설명하고 싶을 때는 문장의 주체가 도구나 기술이 될 수 있어요. 다음 예시와 같은 상황이에요.
Impression 로그는 두 가지 방식으로 동작해요.
1. 특정 접근성 요소가 화면에 나타나면 자동으로 수집돼요.
2. 특정 DOM 요소를 직접 지정해서 뷰포트에 나타날 때 로그를 수집할 수 있어요.
수동형 문장은 문장을 복잡하게 만들고, 주체가 불분명해질 수 있습니다. 능동형 문장을 사용하면 문장이 직관적이고 이해하기 쉬워져요.
애플리케이션이 실행되기 전에 설정이 완료되어야 합니다. 변경 사항이 적용된 후 다시 빌드되어야 합니다.
애플리케이션을 실행하기 전에 설정을 완료하세요. 변경 사항을 적용한 후 다시 빌드하세요.
문장을 짧고 간결하게 유지하세요. 한 문장에 하나의 생각만 담으세요. 짧은 문장은 독자가 내용을 이해하고 정보를 처리하기 더 쉽습니다. 긴 문장은 종종 독자가 주요 포인트를 놓치거나 정보를 잘못 이해하게 만듭니다.
문장이 길어지면 핵심 내용이 묻히고, 독자가 내용을 빠르게 이해하기 어려워져요. 한 문장에는 하나의 생각만 담아보세요.
버튼을 클릭하면 다음 단계로 이동하게 되며, 그 이후의 작업을 진행할 수 있습니다. 이 API를 호출할 때 요청 헤더를 포함해야 하며, 올바른 인증 정보를 제공해야 정상적으로 응답을 받을 수 있습니다.
버튼을 클릭하면 다음 단계로 이동합니다. 이동 후 이어서 작업을 진행하세요. 이 API를 호출할 때 요청 헤더와 인증 정보를 포함하세요.
글쓰기에서 메타 담화(Metadiscourse)란 말 그대로 '말에 대한 말'입니다. 즉, 핵심 메시지 자체가 아니라 그 메시지를 보조하는 표현이에요.
메타 담화가 많으면 문장의 밀도가 낮아지고, 독자가 핵심 정보를 빠르게 파악하기 어려워요. 기술 문서에서는 정보를 빠르게 전달하는 것이 특히 중요하기 때문에 메타 담화 사용을 최소화 하는 게 좋아요.
- 문서의 흐름을 설명하는 표현: '다음으로', '앞서 설명했듯이', '이제 알아보겠습니다'
- 불필요한 강조 표현: '사실은', '솔직히 말하면', '결론적으로'
- 독자의 반응을 유도하는 표현: '아시겠지만', '여러분도 아실 것입니다'
- 앞에서 설명했지만, 결론은 이 설정을 변경하는 것이 가장 효과적인 방법이라는 겁니다.
- 아시다시피, 이 설정은 성능에 영향을 줍니다.
- 이 설정을 변경하는 것이 가장 효과적인 방법입니다.
- 이 설정은 성능에 영향을 줍니다.
아래 문장을 더 간결하고 명확한 문장으로 수정해보세요. 문제를 풀었다면 답안을 확인해서 비교해 보세요.
1. 능동형으로 바꿔보세요.
이 문서는 업데이트된 이후 다시 검토될 필요가 있습니다.
2. 긴 문장을 두 개로 나눠보세요.
사용자는 설정 파일을 변경한 후 저장하고, 변경 사항이 적용되었는지 확인한 다음, 필요하면 서버를 다시 시작해야 합니다.
모호하거나 불필요하게 장황한 표현은 독자의 이해를 방해하고, 중요한 정보를 빠르게 파악하기 어렵게 만들어요. 특히 기술 문서에서는 독자가 필요한 정보를 즉각적으로 찾고 적용할 수 있어야 하기 때문에, 불분명한 표현을 줄이고 직접적이고 구체적인 문장을 작성하는 것이 중요해요.
동사는 명사보다 더 직접적이고 간결하게 독자가 무엇을 해야 하는지에 대한 아이디어를 전달합니다. 특히, 동사에서 파생된 명사(예: "설정 수행", "검토 진행")는 의미가 흐릿해지니 되도록 사용하지 않는 게 좋아요.
코드 최적화 진행 후 배포 수행이 필요합니다.
- '진행', '수행' 같은 불필요한 명사가 포함됐어요.
코드를 최적화한 후 배포하세요
MongoDB 연결 정보 설정 및 초기화가 필요합니다.
- 의미가 함축된 명사가 많고, 어떤 작업을 해야 하는지 명확하지 않아요.
MongoDB에 연결할 호스트와 포트를 설정하고 데이터베이스를 초기화합니다.
'가능성이 있다', '일부 경우', '필요할 수도 있다' 같은 모호한 표현을 사용하면 독자가 정확한 의미를 파악하기 어려워져요. 문서의 신뢰도를 위해 확실한 정보를 제공하세요.
설정 파일을 변경하면 기존 설정이 영향을 받을 수도 있습니다. 일부 브라우저에서 정상적으로 동작하지 않을 가능성이 있습니다.
설정 파일을 변경하면 기존 설정이 삭제됩니다. Internet Explorer에서는 정상적으로 동작하지 않습니다.
아래 문장을 명확하게 수정해보세요. 문제를 풀었다면 답안을 확인해서 비교해 보세요.
1. 명사 대신 동사로 바꿔보세요.
데이터 백업 진행 후 시스템 설정 변경이 필요합니다. 설정 변경 완료 후에는 서비스 재시작 수행이 요구됩니다.
2. 모호한 표현을 명확한 표현으로 바꿔보세요.
일부 환경에서는 소프트웨어 설치 후 정상적으로 실행되지 않을 가능성이 있습니다. 이 경우 추가 구성이 필요할 수도 있습니다.
기술 문서에서는 정확하고 간결한 표현이 중요해요. 불필요한 한자어, 번역체 표현, 잡초 표현을 줄이면 문장이 더 직관적이고 읽기 쉬워져요.
앞서 구체적으로 쓰기에서 설명한 것처럼, 한자어는 문장을 이해하기 어렵게 할 때가 있어요. 특히 '수행하다', '실행하다', '진행하다' 같은 단어는 문장에서 빼도 의미가 잘 전달돼요.
로그 파일을 삭제하는 작업을 수행합니다.
로그 파일을 삭제합니다.
영어에서는 동사를 명사형으로 바꿔서('-tion', '-ing', '-ment', '-ance') 표현하는 게 자연스럽지만, 한국어에서는 동사 그대로 쓰는 게 더 자연스럽습니다. 영어식 명사형 표현을 '무엇을 하는지' 중심으로 자연스럽게 바꿔보세요.
- API 키를 이용한 사용자 인증 처리가 완료된 후, 데이터베이스 접속 설정 진행이 가능합니다.
- 시스템 모니터링 수행을 통해 서버 성능 측정 작업을 실시하게 됩니다.
- 보안 정책 업데이트 진행 후 시스템 재시작 처리를 수행해야 합니다.
- API 키로 사용자를 인증한 후, 데이터베이스에 접속하도록 설정할 수 있습니다.
- 시스템을 모니터링해서 서버 성능을 측정합니다.
- 보안 정책을 업데이트한 후 시스템을 재시작합니다.
아래 문장을 더 자연스럽고 간결한 문장으로 수정해 보세요. 각 문제를 해결한 후, 답안을 확인하여 비교해 보세요.
설정 변경을 수행한 후 적용을 진행합니다.
이 API를 통해 데이터를 가져올 수 있습니다.
기술 문서에서 용어와 표현을 일관되게 사용하는 것은 독자의 이해도를 높이고 문서의 신뢰도를 유지하는 데 중요해요. 같은 개념을 여러 방식으로 표현하면 독자가 혼란을 느낄 수 있으며, 검색과 탐색에도 불편함이 생길 수 있기 때문이죠.
기술 용어는 공식 표기를 따르고, 외래어 표기법은 업계에서 일반적으로 사용되는 형태를 따르는 것을 권장해요.
개발 도구, 언어 등 기술 용어는 위키피디아 및 공식 문서의 이름 표기를 따르세요. 대소문자 표현에 유의하세요.
K8을 사용하면 애플리케이션 배포가 쉬워집니다.
쿠버네티스(Kubernetes)를 사용하면 애플리케이션 배포가 쉬워집니다.
하나의 문서 안에서 같은 개념을 여러 방식으로 표현하면 독자에게 혼란을 줍니다. 의미가 같다면 표현을 일관되게 쓰세요.
파일을 추가하려면 '파일 선택' 버튼을 클릭하세요. 파일을 첨부한 후 '저장'을 누르면 업로드가 완료됩니다. 필요한 경우 파일을 다시 넣을 수 있습니다.
- 같은 개념을 "추가", "첨부", "넣다"처럼 다르게 표현하고 있어요.
파일을 업로드하려면 '파일 선택' 버튼을 클릭하세요. 파일을 업로드한 후 '저장'을 누르면 업로드가 완료됩니다. 필요한 경우 파일을 다시 업로드할 수 있습니다.
괄호 안에 전체 이름을 써주세요. 약어와 괄호 사이는 띄어 쓰지 마세요. 영문 약어를 풀어쓸 때는 전체 이름으로 표현해 주세요.
이 기능은 SSR을 지원합니다.
이 기능은 SSR(Server-Side Rendering)을 지원합니다.
- 처음 등장할 때는 풀어쓰고 약어를 병기하는 게 가장 좋습니다.
기술 문서에서 외래어 표기는 항상 맞춤법을 따르기보다는, 가독성과 독자의 익숙함을 고려해서 업계에서 일반적으로 쓰이는 표현을 고려합니다.
토스에서는 구글 트렌드 기준으로 외래어 표기법보다 5배 이상 많이 사용되는 표기가 있으면 그 표기를 사용해요.
프런트엔드
프론트엔드
- 구글 트렌드 기준으로 기존 표기법보다 5배 이상 많이 사용돼요.
아래 문장을 더 일관된 표현으로 수정해 보고, 답과 비교해 보세요.
이 문서에서는 "자바스크립트 비동기 실행 방식"을 설명합니다.
CSR은 초기 페이지 로딩 속도를 높이는 데 유용합니다.