기술 문서를 튜토리얼·가이드·레퍼런스·해설로 나누는 Diátaxis

• Diátaxis는 기술 문서를 '잘 쓰는 법' 이전에 '왜 읽는지'부터 나누자는 프레임워크임.

  • 문서 사용자는 늘 같은 목적을 갖고 들어오지 않아.
  • 어떤 사람은 처음부터 따라 해보고 싶고, 어떤 사람은 당장 막힌 문제를 해결하고 싶고, 어떤 사람은 정확한 스펙만 확인하고 싶어.

• 이 프레임워크는 문서의 사용자 니즈를 네 가지로 구분함.

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

• 핵심은 이 네 가지를 한 페이지에 비벼 넣지 않는 거임.

  • 초보자용 튜토리얼에 레퍼런스급 세부 옵션을 쏟아부으면 학습 흐름이 깨져.
  • 반대로 레퍼런스 문서가 튜토리얼처럼 장황하면, 이미 알고 있는 사용자는 필요한 값을 찾기 힘들어짐.

• Diátaxis가 다루는 문제는 생각보다 넓음.

  • 무엇을 쓸지라는 콘텐츠 문제를 정리해줘.
  • 어떻게 쓸지라는 스타일 문제도 잡아줘.
  • 어디에 놓을지라는 문서 아키텍처 문제까지 같이 다룸.

• 장점은 가볍고 구현 제약이 거의 없다는 점임.

  • 특정 문서 도구나 사이트 구조를 강제하지 않아.
  • 기존 문서가 위키든 정적 사이트든 제품 문서든, 네 가지 유형으로 재분류해보는 식으로 적용할 수 있음.

---

기술 맥락

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

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

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

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