---
title: "기술 문서를 튜토리얼·가이드·레퍼런스·해설로 나누는 Diátaxis"
published: 2026-08-01T20:33:27.000Z
canonical: https://jeff.news/article/5335
---
# 기술 문서를 튜토리얼·가이드·레퍼런스·해설로 나누는 Diátaxis

Diátaxis는 기술 문서를 사용자 니즈에 따라 튜토리얼, 하우투 가이드, 기술 레퍼런스, 해설 네 가지로 나누는 문서화 프레임워크야. 무엇을 쓸지, 어떤 톤으로 쓸지, 어디에 배치할지까지 문서 구조를 잡는 데 도움을 줘.

- Diátaxis는 기술 문서를 '잘 쓰는 법' 이전에 '왜 읽는지'부터 나누자는 프레임워크임.
  - 문서 사용자는 늘 같은 목적을 갖고 들어오지 않아.
  - 어떤 사람은 처음부터 따라 해보고 싶고, 어떤 사람은 당장 막힌 문제를 해결하고 싶고, 어떤 사람은 정확한 스펙만 확인하고 싶어.

- 이 프레임워크는 문서의 사용자 니즈를 네 가지로 구분함.
  - 튜토리얼은 처음 배우는 사람이 성공 경험을 얻도록 이끄는 문서야.
  - 하우투 가이드는 특정 작업을 끝내기 위한 절차 중심 문서고.
  - 기술 레퍼런스는 API, 설정, 명령어처럼 정확한 정보를 빠르게 찾는 문서임.
  - 해설은 배경, 이유, 설계 의도를 이해시키는 문서에 가까워.

- 핵심은 이 네 가지를 한 페이지에 비벼 넣지 않는 거임.
  - 초보자용 튜토리얼에 레퍼런스급 세부 옵션을 쏟아부으면 학습 흐름이 깨져.
  - 반대로 레퍼런스 문서가 튜토리얼처럼 장황하면, 이미 알고 있는 사용자는 필요한 값을 찾기 힘들어짐.

- Diátaxis가 다루는 문제는 생각보다 넓음.
  - 무엇을 쓸지라는 콘텐츠 문제를 정리해줘.
  - 어떻게 쓸지라는 스타일 문제도 잡아줘.
  - 어디에 놓을지라는 문서 아키텍처 문제까지 같이 다룸.

- 장점은 가볍고 구현 제약이 거의 없다는 점임.
  - 특정 문서 도구나 사이트 구조를 강제하지 않아.
  - 기존 문서가 위키든 정적 사이트든 제품 문서든, 네 가지 유형으로 재분류해보는 식으로 적용할 수 있음.

> [!TIP]
> 문서가 계속 길어지고 찾기 어려워진다면, 먼저 '이 문서는 튜토리얼인가, 하우투인가, 레퍼런스인가, 해설인가'부터 물어보면 됨. 이 질문 하나만으로도 문서 정리가 꽤 빨라져.

---

## 기술 맥락

- Diátaxis의 선택은 문서를 기능 단위가 아니라 사용자 목적 단위로 나누는 거예요. 개발팀은 보통 API나 화면 메뉴 기준으로 문서를 쌓는데, 실제 독자는 그런 구조보다 지금 해야 할 일에 맞는 문서를 찾거든요.

- 튜토리얼과 하우투를 분리하는 이유는 학습과 문제 해결의 리듬이 다르기 때문이에요. 처음 배우는 사람에게는 성공까지 안내하는 흐름이 중요하고, 이미 아는 사람에게는 군더더기 없는 절차가 더 중요해요.

- 기술 레퍼런스와 해설을 따로 두는 것도 같은 이유예요. 레퍼런스는 정확성과 탐색성이 핵심이고, 해설은 왜 그런 설계를 했는지 이해시키는 게 목적이에요. 둘을 섞으면 읽는 사람도 쓰는 사람도 기준을 잃기 쉬워요.

- 팀 규모가 커질수록 이 구분은 더 실용적이에요. 여러 사람이 문서를 고칠 때도 '이 페이지의 역할이 무엇인지'가 정해져 있으면 불필요한 설명 추가나 중복 문서가 줄어들거든요.

## 핵심 포인트

- Diátaxis는 문서 사용자의 목적을 기준으로 문서 유형을 네 가지로 나눠.
- 각 유형은 튜토리얼, 하우투 가이드, 기술 레퍼런스, 해설로 구분돼.
- 문서 작성자에게 콘텐츠, 스타일, 정보 구조를 동시에 정리하는 기준을 제공해.
- 구현 방식에 강한 제약을 걸지 않는 가벼운 프레임워크라 기존 문서에도 적용하기 쉬워.

## 인사이트

개발자 문서가 망하는 흔한 이유가 '처음 배우는 사람', '문제 해결하는 사람', '정확한 스펙 찾는 사람'을 한 페이지에 몰아넣는 거잖아. Diátaxis는 그 혼선을 구조적으로 줄여주는 꽤 실용적인 렌즈야.