테크니컬 라이팅과 일반 글쓰기의 차이는 무엇인가요?

테크니컬 라이팅은 명확성과 정확성이 최우선입니다. 기술적 세부사항, 예제 코드, 단계별 가이드를 포함하며, 독자가 즉시 실행할 수 있도록 작성합니다.

좋은 API 문서의 조건은 무엇인가요?

완전한 엔드포인트 설명, 요청/응답 예제, 에러 코드 설명, 인증 가이드, 코드 샘플을 포함해야 합니다. Stripe와 Twilio가 좋은 예시입니다.

README에 무엇을 포함해야 하나요?

프로젝트 설명, 설치 방법, 빠른 시작, API 레퍼런스, 기여 가이드, 라이선스를 포함해야 합니다. 5분 안에 프로젝트를 이해하고 실행할 수 있어야 합니다.

테크니컬 라이팅 완전 가이드 | 개발자를 위한 효과적인 기술 문서 작성법

2026년 4월 22일 · 32분 읽기 · 수정 2026년 4월 22일 초급 가이드

이 글의 핵심

개발자를 위한 테크니컬 라이팅 가이드. 명확한 API 문서, README, 튜토리얼을 작성하는 방법을 배우고, 구조화·예제 코드·다이어그램으로 독자 친화적인 기술 문서를 만드세요. Google과 Stripe의 원칙을 적용합니다.

이 글의 핵심

테크니컬 라이팅은 개발자가 명확하고 정확한 기술 문서를 작성하는 기술입니다. API 문서, README, 튜토리얼을 작성하는 방법을 배우고, 구조화·예제 코드·다이어그램으로 독자 친화적인 문서를 만드세요.

테크니컬 라이팅이란?
독자 페르소나: 누구를 위해 쓰는가
피라미드 원칙으로 구조 잡기
튜토리얼 vs 레퍼런스
README 작성법
API 문서: 엔드포인트, OpenAPI, JSDoc
튜토리얼 작성법
코드 예제 베스트 프랙티스
다이어그램과 시각 자료
에러 메시지 작성법
문서 유지보수 전략
실제로 겪은 일: 문서가 살아남는 순간
팀 문서화 문화 만들기
체크리스트와 도구

테크니컬 라이팅이란?

테크니컬 라이팅은 기술적 정보를 명확하고 간결하게 전달하는 글쓰기입니다.

🚀 핵심 원칙

1. 명확성 > 화려함

❌ 나쁜 예:
우리의 혁신적인 API는 사용자 경험을 극대화하는 강력한 기능을 제공합니다.

✅ 좋은 예:
이 API는 사용자 데이터를 생성, 조회, 수정, 삭제할 수 있습니다.

2. 구조화

# 좋은 구조
1. 개요 (무엇을 하는가?)
2. 시작하기 (어떻게 시작하는가?)
3. 예제 (실제 사용법)
4. API 레퍼런스 (상세 스펙)
5. 트러블슈팅 (문제 해결)

3. 예제 우선

// ❌ 설명만:
"fetchUsers 함수는 비동기적으로 사용자 목록을 반환합니다."

// ✅ 예제 포함:
"fetchUsers 함수는 사용자 목록을 반환합니다."

const users = await fetchUsers();
console.log(users); // [{ id: 1, name: 'Alice' }, ...]

독자 페르소나: 누구를 위해 쓰는가

문서는 “모든 사람”을 대상으로 쓰면 누구도 만족시키지 못합니다. 페르소나는 과장이 아니라, 한 장짜리 메모에 적을 만큼의 구체성이면 충분합니다. 예를 들어 *“백엔드에 익숙하지만, 우리 팀의 결제 파이프라인은 처음인 시니어 개발자”*처럼 역할, 선행 지식, 막막한 지점을 짚으면, 설명의 깊이가 자연스럽게 맞춰집니다.

항목	잘못 잡은 편향	페르소나를 쓰면
톤	“당연히 다 알겠지”	“이 질문이 오면 이 한 문장으로 끝낸다”
난이도	초급·고급 혼전	한 스토리(온보딩·트러블슈팅)당 한 명
용어	약어·내부 코드명 난무	“첫 언급 풀네임, 이후에만 약어”

Before: “svc-pay 쪽 MRR 보정 루틴 켰으면 DSO 찍히니까 Pager만 보세요.”
After: “결제 집계 배치가 끝나면(약 2분) 대시보드 수치가 갱신됩니다. 그 전까지는 이전날 캐시를 볼 수 있어, ‘어제 수치’가 0에 가깝다면 배치 상태 페이지를 먼저 확인하세요.”

이렇게 “한 번에 한 독자”에 맞추면, 불필요한 자랑·불필요한 위협(공포 마케팅성 문장)이 줄고, 실제로 읽힌 문서가 됩니다.

피라미드 원칙으로 구조 잡기

맥킨지식 피라미드 원칙을 기술 문서에 옮기면, 독자는 위에서 아래로 읽을수록 세부를 얻고, 점프 랜딩(특정 절만 검색)해도 요지가 먼저 보입니다.

결론·행동(한 줄 요약): “이 문서는 X를 하기 위한 것이고, 끝나면 Y를 할 수 있다.”
그룹화: 같은 층의 제목끼리 한 가지 질문에만 답한다. (예: “왜?”, “어떻게?”, “무엇이 바뀌나?”를 한 섹션에 섞지 않기)
논리 순서: 시간 순(튜토리얼), 중요도 순(의사결정 기록), 구조 순(API 레퍼런스) 중 하나를 골라 끝까지 유지

Before (평면적 목록): 설치, 배경, 아키텍처, API, FAQ가 한 페이지에 뒤섞인 README.
After (피라미드): 상단에 *“5분 만에 curl로 성공하는 경로”*를 두고, 배경/아키텍처는 “이미 운영 중인데 원인이 궁금하다” 독자를 위한 링크로 분리

문서 목차는 피라미드의 “층”이 됩니다. 상위 H2는 독자의 의도(무엇을 하려는가)에 맞추는 것이 좋습니다. “개요, 상세, 부록”이 아니라 “빨리 시도 / 깊게 이해 / 망가졌을 때” 같은 흐름이 체감이 큽니다.

튜토리얼 vs 레퍼런스

구분	튜토리얼(가이드)	레퍼런스(스펙)
질문	“처음 어떻게 써?”	“이 필드/함수는 정확히 뭐야?”
흐름	시간 순, 한 번에 끝나는 이야기	가나다·도메인·엔드포인트 등 조회 최적
톤	“이제 `foo`를 호출해보세요”	“`foo`는 인자 a일 때 b를 반환. 오류 c”
업데이트	제품이 바뀌면 경로가 깨짐	스키마/시그니처가 진실; 예제는 짧을수록 좋음

자주 생기는 실수: 랜딩 페이지 하나에 시작하기와 모든 쿼리 인자를 함께 넣는 것. 독자는 “복붙해 성공”을 원하거나 “필드 한 줄”을 찾는데, 서로 스캔 패턴이 다릅니다. 튜토리얼 끝에 *“필드 정의는 API 레퍼런스 → GET /v1/…”*만 링크하세요. 레퍼런스에는 “가장 짧은 성공 curl” 한 블록 정도로 역링크를 두면, 피라미드 상하가 연결됩니다.

README 작성법

필수 섹션

# 프로젝트 이름

한 문장으로 프로젝트 설명.

## 특징

- 주요 기능 1
- 주요 기능 2
- 주요 기능 3

## 설치

\`\`\`bash
npm install my-package
\`\`\`

## 빠른 시작

\`\`\`typescript
import { hello } from 'my-package';

hello('World'); // "Hello, World!"
\`\`\`

## API

### `hello(name: string): string`

인사말을 반환합니다.

**Parameters:**
- `name` (string): 이름

**Returns:**
- (string): 인사말

**Example:**
\`\`\`typescript
hello('Alice'); // "Hello, Alice!"
\`\`\`

## 기여

PR을 환영합니다! [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.

## 라이선스

MIT © [Your Name]

API 문서 작성법

엔드포인트 문서

## GET /users/:id

특정 사용자를 조회합니다.

### URL Parameters

| Name | Type   | Required | Description |
|------|--------|----------|-------------|
| id   | number | Yes      | 사용자 ID   |

### Response

**Status:** 200 OK

\`\`\`json
{
  "id": 1,
  "name": "Alice",
  "email": "[email protected]",
  "createdAt": "2026-04-22T10:00:00Z"
}
\`\`\`

### Errors

| Status | Code           | Message             |
|--------|----------------|---------------------|
| 404    | USER_NOT_FOUND | User not found      |
| 500    | SERVER_ERROR   | Internal server error |

### Example

\`\`\`bash
curl -X GET https://api.example.com/users/1 \\
  -H "Authorization: Bearer YOUR_TOKEN"
\`\`\`

\`\`\`typescript
const user = await fetch('https://api.example.com/users/1', {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
}).then(res => res.json());

console.log(user.name); // "Alice"
\`\`\`

OpenAPI(Swagger)로 “진실”을 한곳에

Before: 런북(Notion)에만 “이 필드 optional이에요”라고 적고, 실제 schema는 코드와 엇갈림.
After: openapi.yaml(또는 서버가 생성)을 스펙의 유일한 소스로 두고, 문서·클라이언트·모킹이 같은 JSON 스키마를 봄.

최소 실전 팁: summary와 description을 다르게 쓰기. summary는 목록·검색용 한 줄, description에 제약(단위, 기본값, idempotency)을 씀.
example은 레퍼런스에, examples는 에러/엣지 설명에.
tags는 제품 팀이 아니라 독자의 작업(Billing, Webhooks) 기준으로 묶는 편이 검색에 유리합니다.

# openapi.yaml (발췌) — "행동"과 "제약"을 스펙에
paths:
  /invoices:
    get:
      summary: 청구서 목록 조회
      description: |
        기본 정렬은 발행일 내림차순입니다.
        `cursor`는 opaque 하며, 다음 페이지 URL은 Link 헤더를 따르세요.
      parameters:
        - in: query
          name: status
          schema:
            type: string
            enum: [draft, open, paid]
          description: 생략 시 전체(단, `void`는 제외)

자동 생성 문서(Stoplight, Redoc, Swagger UI)는 코드와 동기화에 강하므로, “필드 해설만 장문으로 붙이는” 작업을 사람에게만 맡기지 말고, 스키마·예제를 리뷰 대상에 포함하세요.

JSDoc(또는 TSDoc): 코드 옆에 있는 힌트

Before:

// 그냥 any 반환
export function parse(str: any) { /* ... */ }

After:

/**
 * 로그 한 줄을 구조화된 이벤트로 파싱합니다.
 * @param str - JSON Lines 형식(한 줄이 하나의 JSON)입니다.
 * @returns 파싱 실패 시 `null` — 호출 측에서 기본 이벤트로 대체하세요.
 * @example
 * parse('{"t":"order","id":1}') // { t: "order", id: 1 }
 */
export function parse(str: string): LogEvent | null { /* ... */ }

IDE가 시그니처 힌트로 보여 주므로, 레퍼런스를 안 열고도 팀 맴버가 실수를 줄일 수 있습니다.
@throws / @deprecated / @see는 레퍼런스 톤에 맞고, 팀 규칙(예: Public API는 JSDoc 필수)이 있으면 효과가 큽니다.

튜토리얼·레퍼런스와 OpenAPI·JSDoc의 관계

튜토리얼은 여러 API를 잇는 이야기; OpenAPI는 한 엔드포인트의 결정론적 정의.
JSDoc는 함수/타입 단위, OpenAPI는 HTTP 단위. 둘 다 “한 번 정의, 여러 소비(문서, 클라이언트, 검증)”이 목표이면, 중복을 줄이는 파이프라인(스키마에서 타입 생성 등)이 이상적입니다.

튜토리얼 작성법

단계별 가이드

# React로 Todo 앱 만들기

이 튜토리얼에서는 React로 간단한 Todo 앱을 만듭니다.

**소요 시간:** 30분  
**난이도:** 초급  
**필요 지식:** JavaScript 기초, React 기본

## 목차

1. [프로젝트 설정](#1-프로젝트-설정)
2. [컴포넌트 생성](#2-컴포넌트-생성)
3. [상태 관리](#3-상태-관리)
4. [스타일링](#4-스타일링)

## 1. 프로젝트 설정

먼저 Vite로 React 프로젝트를 생성합니다.

\`\`\`bash
npm create vite@latest my-todo-app -- --template react-ts
cd my-todo-app
npm install
npm run dev
\`\`\`

브라우저에서 http://localhost:5173을 열면 기본 화면이 보입니다.

## 2. 컴포넌트 생성

`src/App.tsx`를 다음과 같이 수정합니다.

\`\`\`tsx
import { useState } from 'react';

function App() {
  return (
    <div>
      <h1>Todo App</h1>
    </div>
  );
}

export default App;
\`\`\`

저장하면 브라우저가 자동으로 업데이트됩니다.

## 3. 상태 관리

Todo 목록을 관리할 상태를 추가합니다.

\`\`\`tsx
interface Todo {
  id: number;
  text: string;
  completed: boolean;
}

function App() {
  const [todos, setTodos] = useState<Todo[]>([]);
  const [input, setInput] = useState('');

  const addTodo = () => {
    if (input.trim()) {
      setTodos([...todos, {
        id: Date.now(),
        text: input,
        completed: false
      }]);
      setInput('');
    }
  };

  return (
    <div>
      <h1>Todo App</h1>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        placeholder="New todo..."
      />
      <button onClick={addTodo}>Add</button>
      <ul>
        {todos.map(todo => (
          <li key={todo.id}>{todo.text}</li>
        ))}
      </ul>
    </div>
  );
}
\`\`\`

이제 입력창에 텍스트를 입력하고 "Add" 버튼을 클릭하면 Todo가 추가됩니다.

## 다음 단계

- [ ] 완료 체크 기능 추가
- [ ] 삭제 기능 추가
- [ ] 로컬 스토리지 연동

전체 코드는 [GitHub](https://github.com/example/todo-app)에서 확인할 수 있습니다.

코드 예제 작성법

베스트 프랙티스: 복붙·실행·의미가 한 세트

한 예제 = 한 의도 — “아무 것도 하지 않는” 설정 코드와, 독자가 궁금한 API 호출을 섞지 않기.
버전·환경 — “Node 20, 패키지 foo@^2”처럼 재현 조건을 아주 짧게라도.
출력/검증 — // => 또는 console.log로 기대 결과를 박제하면, “성공”이 명확해짐.
Before/After — 리팩터·보안·성능 문서는 동일 입력에서 무엇이 달라지는지가 핵심.

Before (의도는 좋은데 막힌다):

# 어디에 두고 쓰는지, 권한은?
kubectl apply -f deploy.yaml

After (한 단락으로 맥락 + 재현):

# 프로젝트 루트, staging 네임스페이스, kubeconfig는 ~/.kube/config-staging
kubectl -n myapp-staging apply -f k8s/deploy.yaml
# 배포 후 롤아웃 확인(60초 타임아웃)
kubectl -n myapp-staging rollout status deploy/api --timeout=60s

보안/비밀 — 튜토리얼엔 플레이스홀더를 쓰고, 정책상 가능하면 스코프가 제한된 실제 키 예시(예: 문서용 테스트 프로젝트)를 팀에 공유. 실수로 붙는 일이 가장 흔한 문서 사고 중 하나입니다.

좋은 코드 예제

// ✅ 완전한 예제 (복사해서 바로 실행 가능)
import { createServer } from 'http';

const server = createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World\n');
});

server.listen(3000, () => {
  console.log('Server running at http://localhost:3000/');
});

// ❌ 불완전한 예제 (import 없음, 컨텍스트 부족)
const server = createServer((req, res) => {
  res.end('Hello');
});
server.listen(3000);

다이어그램 활용

텍스트만으로 10문단 쓰는 것과, 다이어그램+짧은 캡션은 전달 효율이 다릅니다. 다만 “멋진 그림”이 목표가 아니라 오해를 줄이는 것이 목표라는 점을 잊지 마세요.

언제 그림이 이길까?

흐름: 인증, 결제, 재시도, DLQ(데드레터)처럼 분기·순서가 핵심일 때(순서도, 시퀀스).
경계: 모듈·팀·데이터 스토어 소유권을 잡을 때(박스화 다이어그램).
스코프: “이 문서는 여기서 여기까지만 다룬다”를 한눈에 보이게.

Before: “A 서비스가 B를 호출하고, 실패 시 C에 넣는데, C는 D에서 소비하며…” (읽다가 끊김)
After: Mermaid 7줄 + 캡션 “쓰기: API→큐, 읽기: 워커→DB(멱등 키로 중복 제거)”

Mermaid로 플로우차트·시퀀스

git이나 문서에 벡터+텍스트로 남는 점이 강합니다. PR 리뷰에서도 “이 다이어그램이 맞나?”로 대화가 빨라짐.

graph TD
    A[사용자 요청] --> B{인증됨?}
    B -->|Yes| C[데이터 조회]
    B -->|No| D[401 Unauthorized]
    C --> E[응답 반환]

시퀀스(대화) 도 같은 도구로 표현해, *“누가 먼저, 무엇을, 실패 시 어떤 응답”*을 한 장에.

스크린샷·UI 문서

한 장에 한 액션 — 저장 버튼과 배포 탭이 한 캡처에 있으면 독자가 시선을 잃습니다.
민감정보는 항상 마스킹(실수로 PII를 문서에 싣는 사고 흔함).
UI가 자주 변하면 스크린샷 비중을 줄이고, 절대 경로(메뉴 depth) 를 텍스트로 병기.

아키텍처 다이어그램(ASCII / 도구 공통)

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Client    │─────▶│     API     │─────▶│  Database   │
│  (React)    │◀─────│  (Node.js)  │◀─────│ (PostgreSQL)│
└─────────────┘      └─────────────┘      └─────────────┘

C4·박스 다이어그램이든, 손그림이든, 범례(실선/점선, 동기/비동기) 를 통일해 두면, 나중에 그림을 갈아끼워도 팀이 혼란을 덜 겪습니다.

에러 메시지 작성법

좋은 에러 메시지

// ✅ 명확하고 해결책 제시
throw new Error(
  'Database connection failed: ' +
  'Please check if PostgreSQL is running on port 5432. ' +
  'See: https://docs.example.com/troubleshooting#db-connection'
);

// ❌ 모호한 에러
throw new Error('Connection failed');

문서 유지보수 전략

문서는 한 번 써 끝이 아니라, 코드와 경쟁합니다. “작성”보다 “낡지 않게”가 어려운 이유죠.

1. “오너”와 만료

페이지/도메인 단위로 문서 담당(코드 담당과 같지 않아도 됨)을 정합니다. “누구한테 PR 보내면 되나”가 검색 한 번에 나오는 게 이상적입니다.
“마지막으로 검증한 날짜 / 다음 검증 due”를 Front matter나 푸터에 두면, 기술 부채를 눈에 띄게 할 수 있습니다(과장은 금지, 실제 점검한 날).

2. PR과 문서의 동기화

Before: 기능 PR은 머지됐는데, 문서는 다음 스프린트로 미뤄짐 → 영원히 미완.
After: 같은 PR에 “문서 변경 없음(이유: …)” 또는 문서/스크린샷/스키마 diff를 포함. “문서 PR 따로”는 예외로만.

3. 자동화가 줄일 것

OpenAPI, 타입, CLI --help에서 같은 소스로 생성되는 부분을 늘림.
링크 깨짐(404) 검사, 예제 스크립트 CI 실행 — 사람의 양심보다 파이프라인이 믿을 만한 경우가 많습니다.

4. 중복을 줄이는 층위

같은 설명이 README·Confluence·내부 위키에 세 번 있으면, 세 곳이 모두 썩습니다. 한 곳이 진실이고 나머지는 링크·요약이 낫다는 걸, 팀이 머릿속으로는 알지만 문서는 자꾸 복붙이 됩니다. “공식은 레포의 docs/”처럼 최우선 층을 하나 박아 두세요.

5. “삭제”도 유지보수

오래된 절(더 이상 아무도 쓰지 않는 v1 마이그레이션)은 과거 기록은 남기되, 현행 경로에서 검색 노이즈로 남지 않게 아카이브하거나, 톤을 바꿔 *“2024년 6월 이전 전용”*을 명시합니다.

실제로 겪은 일: 문서가 살아남는 순간

(아래는 여러 팀에서 반복해 보는 패턴을 한 페르소나의 경험으로 엮은 예입니다. 자신의 상황에 맞게 대입해 읽으면 좋겠습니다.)

온콜 첫날, 페이지가 502였습니다. 런북은 “ALB → 타깃 그룹 확인”까지 친절했는데, 실제 원인은 새로 넣은 환경 변수가 staging에만 있고 prod Secret엔 누락된 것이었죠. 런북을 고친 뒤, 제가 같이 적은 것은 “원인/해결”뿐 아니라 “다음엔 머지 전에 뭐를 보라” 한 줄(예: 배포 체크리스트에 Secret diff)이었습니다. 그때 느꼈습니다. “문서”는 히어로의 일기가 아니라, 다음 사람의 10분이라는걸요.

또 온보딩 문서가 아무리 잘 써도, 첫 풀 req까지 가는 데 3시간이 걸렸다면, 그건 문서가 잘못됐다기보다 도구/스크립트/권한 쪽이 병목인 경우가 많습니다. “문서에 한 줄 더”가 아니라, 빌드가 한 단계라도 적어지게 이슈를 올릴지 결정이 바뀌었습니다. 좋은 문서는 읽는 시간을 줄이는 동시에, 시스템을 손봐야 함을 정직하게 드러냅니다.

팀 문서화 문화 만들기

기술은 개인의 글쓰기 실력만의 문제가 아닙니다. 심리적 안전과 인센티브가 맞지 않으면, 아무리 가이드라인을 써도 “나중에”가 됩니다.

“문서 PR”이 존경받는가: 리뷰어가 “오타 2개뿐이네요”로 빨리 머지해 주는 팀이, “문서는 덜 중요한 일” 팀보다 장기적으로 질이 좋아짐을 자주 봤습니다.
읽힌 문서를 측정(부드럽게): “이번 분기에 가장 많이 열린 문서” 정도는 공유해 볼 만하고, 개인 순위로 쓰면 문화가 망가집니다.
뉴스레터/리캡에 “이번에 바뀐 API / 깨진 링크 0개를 위해 한 일”을 짧게 넣는 것도, “문서가 살아 있다”는 신호입니다.
신입·전입자에게 질문 받기를 문서에 반영하는 루틴 — “1주차 질문 TOP3를 문서에 넣는다”가 팀에선 실제로 작동했습니다.

Before (문화): “다 아는 것 가정하고, 모르면 물어봐~” — 물론 좋은 말이지만, 같은 질문이 슬랙에 매주 뜨면 누구나 지침.
After (문화): “같은 질문 두 번째는 문서/FAQ에, 세 번째는 스크립트/자동화” — 반복을 팀의 자산으로 전환

테크니컬 라이팅 체크리스트

문서 작성 전

대상 독자는 누구인가? (초급/중급/고급)
독자가 얻을 수 있는 것은? (목표)
필요한 사전 지식은? (전제 조건)

문서 작성 중

각 섹션에 명확한 제목이 있는가?
예제 코드가 완전한가? (복사해서 실행 가능)
전문 용어를 설명했는가?
스크린샷/다이어그램이 필요한가?

문서 작성 후

처음 보는 사람도 이해할 수 있는가?
예제를 직접 실행해봤는가?
오타/문법 오류가 없는가?
링크가 모두 작동하는가?

도구 추천

문서 생성

Docusaurus: 정적 문서 사이트
VitePress: Vue 기반 문서
Nextra: Next.js 기반 문서

다이어그램

Mermaid: 코드로 다이어그램 생성
Excalidraw: 손그림 스타일 다이어그램
Draw.io: 무료 다이어그램 도구

스크린샷

CleanShot X: macOS 스크린샷
ShareX: Windows 스크린샷
Flameshot: Linux 스크린샷

핵심 정리

✅ 테크니컬 라이팅 원칙

명확성: 간결하고 정확하게
구조화: 논리적 흐름
예제 우선: 실행 가능한 코드
독자 중심: 대상 독자 고려
반복 개선: 피드백 반영

🚀 다음 단계

시작하기: 오늘부터 README와 코드 주석을 개선하고, 명확한 기술 문서로 더 나은 개발자가 되세요! 🚀

이 글이 도움이 되셨나요?

여러분의 피드백은 더 나은 콘텐츠를 만드는 데 도움이 됩니다

문제가 있거나 개선 제안이 있으시면 연락처로 알려주세요.

Keyboard Shortcuts

이 글의 핵심

이 글의 핵심

목차

테크니컬 라이팅이란?

🚀 핵심 원칙

1. 명확성 > 화려함

2. 구조화

3. 예제 우선

독자 페르소나: 누구를 위해 쓰는가

피라미드 원칙으로 구조 잡기

튜토리얼 vs 레퍼런스

README 작성법

필수 섹션

API 문서 작성법

엔드포인트 문서

OpenAPI(Swagger)로 “진실”을 한곳에

JSDoc(또는 TSDoc): 코드 옆에 있는 힌트

튜토리얼·레퍼런스와 OpenAPI·JSDoc의 관계

튜토리얼 작성법

단계별 가이드

코드 예제 작성법

베스트 프랙티스: 복붙·실행·의미가 한 세트

좋은 코드 예제

다이어그램 활용

언제 그림이 이길까?

Mermaid로 플로우차트·시퀀스

스크린샷·UI 문서

아키텍처 다이어그램(ASCII / 도구 공통)

에러 메시지 작성법

좋은 에러 메시지

문서 유지보수 전략

1. “오너”와 만료

2. PR과 문서의 동기화

3. 자동화가 줄일 것

4. 중복을 줄이는 층위

5. “삭제”도 유지보수

실제로 겪은 일: 문서가 살아남는 순간

팀 문서화 문화 만들기

테크니컬 라이팅 체크리스트

문서 작성 전

문서 작성 중

문서 작성 후

도구 추천

문서 생성

다이어그램

스크린샷

핵심 정리

✅ 테크니컬 라이팅 원칙

🚀 다음 단계

이 글이 도움이 되셨나요?