참조를 위한 문서 📑

참조 문서는 독자가 특정 기술, 도구, 또는 시스템에 대한 정확하고 완전한 정보를 빠르게 찾을 수 있도록 설계된 문서예요. 핵심은 정확성, 완전성, 검색 용이성이며, 독자가 필요할 때 즉시 원하는 정보를 찾아 적용할 수 있어야 해요.

또 함수, 매개변수, 반환값, 사용 예제 같은 구성을 정하고 일관되게 작성해야 해요.

1. 정확성과 완전성이 중요해요

문서에 포함된 모든 정보는 정확해야 하고, 누락된 부분이 없어야 해요. 기술적 오류나 모호한 설명이 없어야 하며, 항상 최신 상태여야 해요.

2. 일관된 구조로 작성해요

일관된 포맷과 구조로 가독성을 높여야 해요. API 문서라면 함수 이름 → 매개변수 → 반환값 → 예제 코드 순과 같은 표준화된 구조를 만들어요.

3. 검색과 탐색이 쉬워요

독자가 필요한 정보를 빠르게 찾을 수 있도록 문서를 체계적으로 구성해야 해요. 목차, 키워드 검색, 앵커 링크 등을 활용해서 정보를 쉽게 탐색할 수 있도록 해야 해요.

4. 예제 코드를 제공해요

명확한 설명과 함께 예제 코드를 함께 제공해야 해요. 예제 코드로 특정 함수나 API를 어떻게 사용하는지 직관적으로 알 수 있어요.

이해하기

fetch API 문서 예시를 보면서 참조 문서 쓰는 법을 간단히 익혀봐요.

# `fetch` API 1`fetch` 함수는 네트워크 리소스를 요청하고 응답을 처리하는 API예요. 비동기적으로 동작하고, `Promise<Response>` 객체를 반환해요. `fetch` 함수를 활용하면 클라이언트와 서버 간 데이터를 쉽게 주고받을 수 있어, REST API와 같은 서비스와의 통신을 효율적으로 처리할 수 있어요.`XMLHttpRequest`보다 간결한 문법을 제공하고, `async/await`와 함께 사용하면 가독성이 뛰어나다는 장점도 있어요. ## 시그니처 2```typescriptfetch(input: RequestInfo, init?: RequestInit): Promise<Response>``` 3## 매개변수 - `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<object>)  - `text`(): 응답을 문자열로 변환 (Promise<string>)  - `blob`(): 응답을 Blob 객체로 변환 (Promise<Blob>)  ## 사용 예제 4### 기본 GET 요청 ```javascriptfetch('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));```  ### POST 요청 예제 ```javascriptfetch('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));``` 5### async/await 사용 ```javascriptasync 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();``` 
1
fetch 함수에 대해 간단히 설명해요. 기능 뿐만 아니라 이 함수가 제공하는 가치를 설명해요.
2
함수의 시그니처를 설명해요. 시그니처를 작성하면 함수의 입력값과 반환값을 직관적으로 파악할 수 있어요. 이를 통해 개발자는 함수의 동작 방식을 빠르게 이해하고, 올바른 매개변수를 전달할 수 있어요.
3
fetch 함수의 매개변수와 반환값을 정리해요. Response 객체의 주요 속성을 나열하고, 반환값을 다루는 방법을 쉽게 이해할 수 있도록 했습니다.
4
기본적인 사용 예제를 제공해요. fetch를 활용하여 데이터를 가져오는 방법과 오류 처리를 함께 설명했습니다.
5
기본 예제 뿐 아니라 독자가 활용할 수 있도록 추가로 참고할만한 코드 예제도 추가할 수 있어요.

더 나아가기

참조 문서는 방대한 양의 정보를 포함하기 때문에 독자가 원하는 내용을 빠르게 찾기 어려울 수 있어요. 이를 해결하기 위해 주제별로 섹션을 나누고 목차를 제공하면 탐색이 쉬워져요. 다음 예시 문서를 보면 결제라는 도메인을 주제별로 나누고 오른쪽에 API별 목차를 제공하고 있어요.

또, 독자가 참조 문서를 활용하기 전에 반드시 알아야 할 정보의 배치도 신경쓰면 좋아요. 독자가 항상 참조 문서를 활용하는 시점에만 문서를 보는 게 아니기 때문에 사전에 알아야 할 정보가 있을 수 있어요. 예를 들면 API 키 설정, 인증 방식, 요청 헤더 구성 같은 핵심 정보를 문서의 앞부분에 두어 눈에 잘 띄도록 하면 좋아요. 덕분에 독자가 문서를 처음 접했을 때 필요한 내용을 놓치지 않을 수 있었어요.

체크리스트

  • 검색 및 탐색이 쉬운 구조인가요?
  • 정보가 정확하고 완전한가요?
  • 문서가 일관된 구조와 형식으로 작성되어 있나요?
  • 실용적인 예시 코드가 포함되어 있나요?