Diátaxis로 정리하는 기술 문서 작성 체계와 네 가지 문서 유형

기술 문서를 작성하다 보면 생각보다 자주 막히는 지점이 있습니다. 어떤 내용을 작성해야 하는지는 알고 있지만, 그 내용을 어떤 문서에 담아야 하는지 판단하기 어려운 경우입니다. 사용 방법을 설명해야 하는지, 개념부터 설명해야 하는지, 아니면 시스템의 정확한 정보를 정리해야 하는지도 애매할 수 있습니다.

문서가 많아질수록 이런 문제는 더 커집니다. 필요한 정보가 여러 문서에 흩어지거나 문서마다 목적이 달라지고, 새로운 문서를 추가할 때도 어디에 배치해야 할지 판단하기 어려워집니다.

Diátaxis는 이러한 기술 문서의 문제를 사용자의 요구를 기준으로 바라보는 체계적 접근법입니다. 문서를 튜토리얼, 방법 안내서, 기술 참조, 설명이라는 네 가지 유형으로 구분하고, 각 문서가 어떤 사용자 요구를 해결해야 하는지 명확하게 합니다.

이 글에서는 Diátaxis가 무엇인지부터 네 가지 문서 유형의 차이, 해결하려는 문서화 문제, 실제 적용 방법과 도입 사례까지 살펴보겠습니다.

반응형

Diátaxis란 무엇인가

Diátaxis는 기술 문서를 작성하는 방법인 동시에 문서를 바라보는 사고 체계입니다.

핵심은 단순합니다. 문서를 먼저 작성하고 사용자가 알아서 이해하기를 기대하는 것이 아니라, 문서를 사용하는 사람이 무엇을 필요로 하는지 먼저 파악한 뒤 그 요구에 맞춰 콘텐츠와 구조를 설계하는 것입니다.

이를 위해 Diátaxis는 사용자의 요구를 네 가지 유형으로 나눕니다.

• 튜토리얼
• 방법 안내서
• 기술 참조
• 설명

각 유형은 서로 다른 목적을 가집니다. 따라서 하나의 문서 형식으로 모든 정보를 해결하려 하기보다는, 사용자가 어떤 상황에서 문서를 찾는지를 기준으로 적절한 유형을 선택하는 것이 중요합니다.

Diátaxis는 콘텐츠만 다루는 접근법도 아닙니다. 무엇을 작성할지뿐만 아니라 어떻게 전달할지, 그리고 여러 문서를 어떤 관계와 구조로 배치할지도 함께 다룹니다.

즉, 기술 문서를 단순한 정보의 모음이 아니라 사용자의 요구를 중심으로 구성된 정보 체계로 바라보는 것입니다.

Diátaxis가 해결하려는 기술 문서의 문제

기술 문서를 운영하면서 발생하는 문제는 단순히 내용이 부족해서 생기지 않습니다. 필요한 정보가 충분히 들어 있어도 사용자가 원하는 내용을 찾기 어렵다면 좋은 문서라고 보기 어렵습니다.

Diátaxis는 기술 문서에서 발생하는 문제를 크게 세 가지 관점에서 바라봅니다.

어떤 콘텐츠를 작성해야 하는가

첫 번째는 콘텐츠의 문제입니다.

문서를 작성할 때 가장 먼저 생기는 질문은 "무엇을 작성해야 하는가?"입니다.

예를 들어 어떤 기술의 사용 방법을 설명하는 문서가 있다고 가정해 보겠습니다. 사용자가 따라 할 수 있는 단계별 과정이 필요한 것인지, 해당 기술의 구성과 동작에 대한 정확한 정보가 필요한 것인지에 따라 작성해야 할 내용은 달라집니다.

사용자의 요구가 다른데도 하나의 문서에 모든 정보를 담으려고 하면 문서의 목적이 불명확해질 수 있습니다.

어떻게 전달해야 하는가

두 번째는 문체와 형식의 문제입니다.

같은 기술을 설명하더라도 문서의 목적에 따라 정보를 전달하는 방식이 달라져야 합니다.

사용자가 처음 기술을 배우는 상황이라면 학습을 따라갈 수 있는 방식으로 설명해야 합니다. 반면 특정 작업을 해결하려는 사용자는 필요한 작업을 빠르게 수행할 수 있는 방법을 찾을 가능성이 높습니다.

따라서 문서의 목적에 맞춰 정보의 전달 방식과 형식을 결정해야 합니다.

문서를 어디에 배치해야 하는가

세 번째는 정보 구조의 문제입니다.

문서가 하나뿐이라면 위치를 고민할 필요가 없지만, 문서가 계속 늘어나면 이야기가 달라집니다.

새로운 문서를 작성했을 때 기존 문서와 어떤 관계를 갖는지, 어느 영역에 배치해야 하는지, 기존 문서의 내용을 이동하거나 나눠야 하는지 판단해야 합니다.

Diátaxis는 이러한 상황에서 문서의 목적과 사용자 요구를 기준으로 문서의 위치와 관계를 판단할 수 있는 기준을 제공합니다.

Diátaxis의 네 가지 문서 유형

Diátaxis의 핵심은 네 가지 문서 유형입니다.

각 유형은 서로 대체되는 관계가 아니라 서로 다른 사용자 요구를 충족하며 연결됩니다.

1. 튜토리얼

튜토리얼은 사용자가 학습 경험을 따라가면서 새로운 능력을 얻도록 안내하는 문서입니다.

여기서 중요한 것은 단순히 정보를 전달하는 것이 아니라 사용자가 학습할 수 있도록 경험을 구성하는 것입니다.

사용자가 어떤 기술을 처음 접한다고 생각해 보면 이해하기 쉽습니다. 이 경우 사용자는 단순히 기술의 정확한 구성 정보를 원하는 것이 아니라, 기술을 이해하고 직접 경험하면서 새로운 능력을 얻는 과정이 필요할 수 있습니다.

따라서 튜토리얼은 학습이라는 요구에 맞춰 구성됩니다.

2. 방법 안내서

방법 안내서는 사용자가 특정 목표나 작업을 완수하도록 돕는 문서입니다.

튜토리얼이 새로운 능력을 얻는 학습 경험에 초점을 둔다면, 방법 안내서는 특정 작업을 해결하는 것에 초점을 둡니다.

사용자가 이미 관련 기술을 어느 정도 알고 있고 특정한 목표를 달성해야 하는 상황을 생각하면 됩니다.

이때 문서는 사용자가 원하는 작업을 수행할 수 있도록 필요한 내용을 중심으로 구성해야 합니다.

3. 기술 참조

기술 참조는 제품이나 시스템의 구성과 동작에 관한 정확한 정보를 제공하는 문서입니다.

사용자가 학습하거나 특정 작업을 따라 하는 것보다, 시스템에 대한 정확한 정보를 확인해야 할 때 활용되는 유형입니다.

따라서 기술 참조에서는 무엇보다 정확한 정보 제공이 중요합니다.

제품이나 시스템의 구성과 동작에 관한 정보를 확인하기 위해 찾는 문서라는 점에서 튜토리얼이나 방법 안내서와는 목적이 다릅니다.

4. 설명

설명은 사용자가 개념과 맥락을 이해하고 지식을 연결할 수 있도록 돕는 문서입니다.

기술 문서를 읽다 보면 단순한 사용 방법만으로는 이해하기 어려운 개념이 있습니다. 특정 기술이 왜 필요한지, 어떤 맥락에서 이해해야 하는지 알지 못하면 관련 정보를 알고 있더라도 전체적인 의미를 파악하기 어려울 수 있습니다.

설명은 이러한 이해를 돕는 역할을 합니다.

즉, 단순히 무엇을 해야 하는지를 알려주는 것이 아니라 개념과 맥락을 이해하고 기존 지식과 연결할 수 있도록 돕는 것이 핵심입니다.

네 가지 문서 유형은 서로 연결된다

Diátaxis의 네 가지 문서 유형을 단순히 "문서를 네 종류로 나누는 방법"이라고 이해하면 핵심을 놓칠 수 있습니다.

네 유형은 서로 대체되는 형식이 아닙니다.

튜토리얼은 학습을 돕고, 방법 안내서는 특정 작업을 해결하도록 돕습니다. 기술 참조는 정확한 정보를 제공하고, 설명은 개념과 맥락을 이해하도록 돕습니다.

즉, 같은 사용자가 문서를 이용하더라도 상황에 따라 필요한 문서 유형이 달라질 수 있습니다.

이 관점에서 보면 Diátaxis는 문서를 각각 따로 관리하기 위한 분류법이 아니라, 서로 다른 사용자 요구를 충족시키는 문서 체계를 구성하기 위한 접근법이라고 볼 수 있습니다.

작성자와 유지보수자에게도 필요한 이유

Diátaxis의 특징 중 하나는 문서 사용자뿐 아니라 문서를 작성하고 관리하는 사람에게도 적용할 수 있다는 점입니다.

문서를 작성하다 보면 새로운 콘텐츠를 어디에 넣어야 할지 판단하기 어려운 순간이 생깁니다.

이때 Diátaxis의 관점에서는 먼저 해당 콘텐츠가 어떤 사용자 요구를 해결하는지 살펴볼 수 있습니다.

또한 기존 문서의 목적이 명확하지 않다면 현재 문서가 어떤 요구를 해결하고 있는지 다시 살펴볼 수 있습니다.

이를 통해 다음과 같은 판단에 활용할 수 있습니다.

• 새 문서를 어떤 유형으로 분류할 것인가
• 기존 문서가 어떤 목적을 가지고 있는가
• 문서의 위치가 적절한가
• 여러 문서의 역할이 겹치고 있지는 않은가
• 필요한 정보가 사용자가 찾기 쉬운 구조로 배치되어 있는가

따라서 Diátaxis는 문서 작성자와 유지보수자가 자신의 작업을 판단할 수 있는 능동적인 품질 원칙으로 활용할 수 있습니다.

Diátaxis는 특정 도구나 기술을 요구하지 않는다

Diátaxis를 적용하기 위해 특정 문서 작성 도구나 플랫폼을 사용할 필요는 없습니다.

이 접근법은 특정 구현 방식에 제약을 두지 않으며, 문서를 어떤 도구로 작성하고 관리하는지보다 사용자 요구를 기준으로 콘텐츠와 구조를 설계하는 것에 초점을 둡니다.

이러한 특성은 기존 문서 체계를 가지고 있는 조직에서도 의미가 있습니다.

이미 많은 문서가 존재하는 상황에서 문서 전체를 한 번에 새롭게 구성하는 것은 쉽지 않습니다. Diátaxis는 기존 문서의 목적과 위치를 하나씩 살펴보거나 새로운 문서를 분류하는 방식으로 점진적으로 적용할 수 있습니다.

Diátaxis를 실제 문서에 적용하는 방법

Diátaxis의 적용을 시작하는 방법은 비교적 간단하게 제시됩니다.

먼저 짧은 입문 문서를 통해 기본 개념을 이해하고, 이를 실제 문서에 적용하는 방식입니다.

제공된 자료에서는 다음과 같은 항목을 통해 구체적인 적용 방법과 개념을 확인할 수 있습니다.

• Start here
• Applying Diátaxis
• The compass
• Workflow

기본 개념을 이해한 뒤 실제 문서를 살펴보면서 각각의 문서가 어떤 사용자 요구를 해결하고 있는지 판단해 보는 방식으로 접근할 수 있습니다.

또한 Diátaxis의 원리와 설계 방식을 더 깊게 이해하기 위한 자료도 제공됩니다.

주요 내용으로는 다음과 같은 항목이 있습니다.

• Understanding Diátaxis
• Foundations
• The map
• Quality
• Tutorials and how-to guides
• Reference and explanation
• Complex hierarchies

이를 통해 단순히 네 가지 문서 유형을 암기하는 것이 아니라, 그 뒤에 있는 원리와 문서 설계 방식을 이해할 수 있습니다.

실제 도입 사례로 보는 Diátaxis

Diátaxis는 실제 문서화 프로젝트에도 도입된 사례가 소개되어 있습니다.

Vonage

Vonage는 Diátaxis를 활용해 사용자가 선호하고 기여자도 문서를 추가하기 쉬운 고품질 내부 문서 체계를 구축하는 데 활용했습니다.

이를 통해 Diátaxis가 문서 사용자뿐 아니라 문서를 작성하고 기여하는 사람에게도 적용될 수 있다는 점을 확인할 수 있습니다.

Gatsby

Gatsby는 오픈소스 문서를 재구성하면서 네 가지 영역을 기준으로 각 문서가 해결해야 하는 사용자 목표를 정했습니다.

이를 통해 필요한 자료를 필요한 시점에 찾기 쉽도록 문서를 개선했습니다.

단순히 문서를 많이 만드는 것이 아니라, 각 문서가 어떤 사용자 목표를 해결하는지 기준을 세웠다는 점이 핵심입니다.

Cloudflare

Cloudflare는 개발자 문서의 정보 구조를 개편할 때 Diátaxis를 기준으로 활용했습니다.

특히 새로운 콘텐츠를 어디에 배치해야 할지 불분명한 상황에서 프레임워크를 판단 기준으로 사용했습니다.

그 결과 독자와 기여자 모두에게 문서 구조가 이전보다 명확해졌다고 소개됩니다.

이 사례들은 Diátaxis가 단순한 문서 작성 이론에 머무르지 않고 실제 문서 구조를 검토하고 개선하는 기준으로 활용될 수 있음을 보여줍니다.

Diátaxis가 기술 문서에 주는 의미

기술 문서의 품질을 이야기할 때 문서에 얼마나 많은 정보가 들어 있는지만 보는 것은 충분하지 않습니다.

사용자가 원하는 정보를 적절한 방식으로 찾을 수 있는지도 중요합니다.

Diátaxis는 이 문제를 사용자 요구에서 출발해 바라봅니다.

"무엇을 작성할 것인가"에서 시작해 "어떻게 전달할 것인가", "어디에 배치할 것인가"까지 연결함으로써 개별 문서의 품질뿐 아니라 전체 문서 구조를 함께 살펴볼 수 있도록 합니다.

특히 문서가 계속 증가하는 환경에서는 이러한 기준이 중요해질 수 있습니다.

문서가 많아질수록 새로운 내용을 추가하는 것보다 각각의 문서가 어떤 목적을 가지고 있으며 서로 어떤 관계를 갖는지 관리하는 일이 중요해지기 때문입니다.

728x90

Diátaxis는 기술 문서를 튜토리얼, 방법 안내서, 기술 참조, 설명이라는 네 가지 유형으로 구분하고, 사용자의 요구를 중심으로 문서의 콘텐츠와 형식, 정보 구조를 설계하는 체계적 접근법입니다.

핵심은 단순히 문서를 네 종류로 나누는 데 있지 않습니다.

사용자가 어떤 상황에서 문서를 찾는지 이해하고, 그 요구에 맞는 콘텐츠를 제공하며, 여러 문서가 서로 명확한 관계를 갖도록 구성하는 것이 핵심입니다.

이를 통해 문서 작성자는 새로운 콘텐츠를 어디에 배치할지 판단할 수 있고, 유지보수자는 기존 문서의 목적과 위치를 다시 검토할 수 있습니다.

또한 특정 문서 도구나 플랫폼을 요구하지 않기 때문에 기존 문서 체계에도 점진적으로 적용할 수 있다는 특징이 있습니다.

기술 문서가 많아질수록 중요한 것은 단순히 더 많은 내용을 작성하는 것이 아닙니다. 필요한 사람이 필요한 정보를 적절한 형태로 찾을 수 있도록 문서 전체의 구조와 역할을 명확하게 만드는 것이 중요합니다.

Diátaxis는 이러한 관점에서 기술 문서를 바라보고 개선할 수 있는 하나의 기준을 제공합니다. 특히 Vonage, Gatsby, Cloudflare와 같은 실제 도입 사례를 통해 문서의 정보 구조와 탐색성을 개선하는 방향으로 활용될 수 있다는 점도 확인할 수 있습니다.

결국 Diátaxis가 제시하는 핵심은 명확합니다. 좋은 기술 문서는 정보를 많이 담은 문서가 아니라, 사용자가 무엇을 필요로 하는지에 맞춰 적절한 정보를 적절한 방식으로 제공하는 문서여야 한다는 것입니다.

300x250

https://diataxis.fr/

Diátaxis