예측 가능하게 하기

문서는 독자가 쉽게 탐색하고 필요한 정보를 빠르게 찾을 수 있도록 예측 가능해야 합니다. 예측 가능한 문서 구조는 독자가 내용을 이해하는 데 드는 인지 부담을 줄이고, 문서를 효율적으로 활용할 수 있도록 돕습니다.

예측 가능한 문서는 일관된 용어와 표현을 사용하고, 설명의 흐름이 자연스럽게 연결되며, 새로운 정보가 논리적인 순서로 배치됩니다.

1. 독자가 문서를 빠르게 탐색할 수 있습니다

문서가 일관된 구조를 가지면, 독자는 필요한 정보를 쉽게 찾을 수 있습니다. 예측 가능성이 낮으면 독자는 어디에서 원하는 내용을 찾아야 할지 혼란스러워질 수 있습니다.

2. 학습 곡선을 줄일 수 있습니다

일관된 제목, 형식, 문단 구조를 유지하면, 새로운 문서를 접할 때도 기존 문서의 흐름을 연장해서 이해할 수 있습니다. 특히 문서가 많아질수록 예측 가능성이 더욱 중요합니다.

3. 유지보수가 쉬워집니다

예측 가능한 문서 구조는 팀 내에서 문서를 유지보수할 때도 큰 도움이 됩니다. 일관된 패턴을 따르면 어떤 정보를 어디에 위치시켜야 하는지 쉽게 결정할 수 있습니다.

체크리스트

✅ 일관된 제목, 형식, 구조를 유지하세요

Don't

# API 요청 최적화

이 문서에서는 API 요청을 최적화하는 여러 가지 방법을 설명합니다.

## 성능 향상 기법
- 캐싱 활용하기
- 요청 병합하기

### API 속도 측정
API 응답 속도를 분석하는 방법을 설명합니다.

## 오류 처리
API 요청 중 발생할 수 있는 문제와 해결책을 설명합니다.

섹션 간의 위계가 불규칙하고, 각 내용이 어떻게 연결되는지 명확하지 않습니다.

Do

# API 요청 최적화

API 요청을 줄이고 성능을 향상시키는 방법을 알아봅니다.

## 1. 성능 향상 기법
### 캐싱 활용하기
### 요청 병합하기

## 2. API 속도 측정

API 응답 속도를 분석하는 방법을 설명합니다.

## 3. 오류 처리

API 요청 중 발생할 수 있는 문제와 해결책을 설명합니다.

같은 수준의 개념을 일관된 위계로 정리하여 예측 가능성을 높였습니다.

✅ 섹션 제목은 동일한 패턴을 따르세요

문서마다 섹션 이름이 다르면 독자가 어디서 원하는 정보를 찾아야 할지 혼란스러울 수 있어요. 예를 들어, 한 문서에서 "설치", 다른 문서에서 "환경 설정"이라고 표현하면 독자는 두 개의 섹션이 같은 내용을 다루는지 헷갈릴 수 있죠. 문서 전체에서 통일된 섹션 이름과 순서를 유지하면 독자가 여러 문서를 이동하면서도 자연스럽게 내용을 탐색하는데 도움이 돼요.

Don't

## API 요청 예제

fetch("https://api.example.com/data")
  .then(response => response.json())
  .then(data => console.log(data));

이 코드는 서버에서 데이터를 가져와 JSON으로 변환하는 코드입니다.

독자는 코드가 어떤 역할을 하는지 알지 못한 채 먼저 코드를 해석해야 합니다.

Do

## API 요청 예제

서버에서 데이터를 가져와 JSON으로 변환하는 방법을 알아봅니다.

fetch("https://api.example.com/data")
  .then(response => response.json())
  .then(data => console.log(data));

설명이 먼저 나오고, 그다음 예제 코드가 제공되어 독자가 내용을 쉽게 예측할 수 있습니다.

✅ 논리적인 순서로 정보를 배치하세요

기본 개념부터 설명하고 점진적으로 확장하세요. 문서를 읽는 독자는 처음부터 모든 내용을 알고 있지 않습니다. 먼저 개념을 명확하게 정의한 후, 점진적으로 세부 사항과 복잡한 개념을 추가하세요. 예를 들어, 핵심 개념 → 구체적인 사용법 → 예제 코드 → 심화 내용의 순서로 정보를 배치하세요.

Don't

# React에서 useEffect 사용하기

## 비동기 데이터 요청하기
...
## 기본적인 사용법
...
## 클린업 함수 활용하기
...

useEffect의 기본 사용법을 설명하기 전에 비동기 데이터 요청 방법이 먼저 등장하면 독자가 내용을 이해하기 어려워집니다.

Do

# React에서 useEffect 사용하기

## 기본적인 사용법
...
## 비동기 데이터 요청하기
...
## 클린업 함수 활용하기
...

✅ 용어를 일관되게 사용하세요

용어가 일관되지 않으면 독자는 각 문서에서 같은 개념을 다루는지, 아니면 다른 내용을 설명하는지 판단하기 어려워집니다. 예를 들면 하나의 문서 안에서 "Error Handling"과 "오류 처리"가 혼용되지 않도록 통일합니다.

주요 개념에 대한 용어사전이나 용어 가이드라인을 만들고 문서를 작성할 때 일관되게 적용하세요.

Don't

React에서 상태를 관리하는 방법에는 여러 가지가 있습니다. 컴포넌트 내부에서 데이터 저장을 위해 useState를 사용할 수 있습니다. 값 유지가 필요할 때는 useReducer를 고려할 수 있습니다.

"상태(state)", "데이터(data) 저장", "값(value) 유지"가 혼용되어 사용되었습니다. 독자는 "상태"와 "데이터", "값"이 같은 개념을 의미하는지 혼란스러울 수 있습니다

Do

React에서 상태(state)를 관리하는 방법에는 여러 가지가 있습니다. 컴포넌트 내부에서 상태를 저장하기 위해 useState를 사용할 수 있습니다. 또한, 더 복잡한 상태 관리가 필요할 경우 useReducer를 고려할 수 있습니다.

"상태(state)"라는 용어를 일관되게 사용하여 같은 개념을 설명하고 있다는 것을 명확히 했습니다. "데이터 저장", "값 유지" 대신 "상태 저장", "복잡한 상태 관리"처럼 명확한 표현을 사용했습니다.

ON THIS PAGE

#예측 가능하게 하기

#1. 독자가 문서를 빠르게 탐색할 수 있습니다

#2. 학습 곡선을 줄일 수 있습니다

#3. 유지보수가 쉬워집니다

#체크리스트

#✅ 일관된 제목, 형식, 구조를 유지하세요

Don't

Do

#✅ 섹션 제목은 동일한 패턴을 따르세요

Don't

Do

#✅ 논리적인 순서로 정보를 배치하세요

Don't

Do

#✅ 용어를 일관되게 사용하세요

Don't

Do

예측 가능하게 하기

1. 독자가 문서를 빠르게 탐색할 수 있습니다

2. 학습 곡선을 줄일 수 있습니다

3. 유지보수가 쉬워집니다

체크리스트

✅ 일관된 제목, 형식, 구조를 유지하세요

✅ 섹션 제목은 동일한 패턴을 따르세요

✅ 논리적인 순서로 정보를 배치하세요

✅ 용어를 일관되게 사용하세요