Skip to content
←

Split View: Diátaxis를 네 개의 폴더로 오해하는 이유 — 한 문서 안에 두 모드를 섞으면 왜 무너지는가

✨ Learn with Quiz
|

Diátaxis를 네 개의 폴더로 오해하는 이유 — 한 문서 안에 두 모드를 섞으면 왜 무너지는가

튜토리얼을 열고 30분 만에 창을 닫은 적이 있다면

처음 쓰는 라이브러리의 공식 튜토리얼을 열었다고 해 봅시다. 1번 항목에서 설치를 시키고, 2번에서 예제를 실행시킵니다. 여기까지는 좋습니다. 그런데 3번 항목이 갑자기 "이 값은 세 가지 방식으로 설정할 수 있으며, 프로덕션에서는 두 번째를 권장합니다"로 시작합니다. 세 가지 중에 무엇을 골라야 할지 모르는 상태에서 선택지가 셋 주어집니다. 4번에서는 내부 동작 원리가 두 문단 등장하고, 5번은 다시 명령어로 돌아옵니다.

이 문서는 틀린 정보를 담고 있지 않습니다. 문장도 멀쩡합니다. 그런데 읽는 사람은 30분쯤 지나 창을 닫습니다. 문서 팀이 이 사실을 알게 되는 경로는 보통 "문서가 부족하다"는 피드백인데, 그 피드백을 받고 하는 일은 대개 내용을 더 넣는 것입니다. 그러면 다음 사람은 25분 만에 창을 닫습니다.

네 개의 폴더를 만드는 것은 적용이 아닙니다

이 문제에 이름을 붙인 것이 Diátaxis입니다. 튜토리얼, 하우투 가이드, 레퍼런스, 설명 네 가지로 문서를 나눕니다. 널리 알려져 있고 널리 인용되지만, 실제 팀에서 벌어지는 적용은 대개 여기서 멈춥니다. 문서 저장소에 폴더를 네 개 만들고, 기존 문서를 그 아래로 옮기고, 끝입니다.

그런데 프레임워크를 만든 쪽이 이 방식을 명시적으로 말립니다. Diátaxis 워크플로 문서는 시작할 때 문서를 네 구역으로 나눌 필요가 없다고 말하고, 내용 없는 빈 네 섹션을 만드는 것에 대해서는 그러지 말라고 못을 박습니다. 구조는 개선의 결과로 나중에 나타나는 것이지, 개선을 위해 먼저 부과하는 것이 아니라는 것입니다. 저자는 이를 두고 Diátaxis가 문서의 구조를 안쪽에서부터 바꾼다고 표현합니다.

네 개인 이유는 두 개의 축 때문입니다

왜 하필 넷인지가 중요합니다. 셋도 다섯도 아닌 이유가 없다면 이건 그냥 편한 분류이고, 편한 분류는 애매한 문서 앞에서 아무 도움이 되지 않습니다.

Diátaxis의 근거 문서는 기술을 쓰는 사람을 두 축으로 놓습니다. 하나는 행동과 인지입니다. 어떤 기술이든 무엇을 하는지에 관한 실천적 앎과 무엇이 참인지에 관한 이론적 앎을 동시에 갖습니다. 다른 하나는 습득과 적용입니다. 사람은 기술을 익히는 중이거나, 이미 익힌 기술을 쓰는 중입니다. 공부하는 상태와 일하는 상태라고 바꿔 말해도 됩니다.

두 축이 서로 독립이므로 사분면은 반드시 넷입니다. 학습 욕구는 튜토리얼이, 목표 달성 욕구는 하우투가, 정보 욕구는 레퍼런스가, 이해 욕구는 설명이 맡습니다. 넷은 임의로 고른 숫자가 아니라 영역을 남김없이 덮는 최소 개수입니다.

나침반 — 문단 하나에 두 질문만 던지기

지도는 기억하기 좋지만 애매한 문서 앞에서는 직관이 자주 틀립니다. 그래서 Diátaxis는 나침반이라는 판정표를 따로 둡니다. 물어야 할 것은 두 가지뿐입니다.

이 내용이 다루는 것사용자가 지금 처한 상태그러면 이것은
행동습득(공부 중)튜토리얼
행동적용(일하는 중)하우투 가이드
인지적용(일하는 중)레퍼런스
인지습득(공부 중)설명

중요한 것은 이 표를 문서 단위가 아니라 문단 단위로도 쓸 수 있다는 점입니다. 실제로 Diátaxis는 문장과 단어 수준에서도 적용해 보라고 권합니다. 앞에서 본 튜토리얼 3번 항목을 이 표에 넣으면 바로 답이 나옵니다. 세 가지 설정 방식을 나열한 부분은 인지를 다루고 일하는 사람을 향하므로 레퍼런스입니다. 프로덕션 권장 사유는 인지이면서 공부하는 사람을 향하므로 설명입니다. 한 문서 안에 세 모드가 들어 있었던 겁니다.

가장 흔한 혼동은 튜토리얼과 하우투 사이에서 납니다

Diátaxis는 소프트웨어 문서에서 가장 흔한 혼동이 튜토리얼과 하우투 사이의 혼동이라고 지적합니다. 이유는 단순합니다. 둘은 겉모습이 거의 같습니다. 둘 다 번호가 붙은 단계를 제시하고, 둘 다 순서대로 따라 하면 성공한다고 약속하고, 둘 다 손을 움직이지 않는 독자에게는 쓸모가 없습니다.

차이는 형식이 아니라 섬기는 필요에 있습니다. 튜토리얼은 공부 중인 사람을, 하우투는 일하는 중인 사람을 섬깁니다. 여기서 자주 나오는 두 번째 오해가 튜토리얼은 기초, 하우투는 고급이라는 구분인데 이것도 틀립니다. 문서 원문은 하우투가 기초적인 절차를 다룰 수 있고 또 다뤄야 한다고 말하고, 반대로 아주 숙련된 사람을 위한 고난도 튜토리얼도 가능하다고 말합니다. 갈리는 지점은 난이도가 아니라 독자가 공부 중인지 일하는 중인지입니다.

두 상태는 정반대의 것을 요구합니다

섞으면 무너지는 이유가 여기서 나옵니다. 두 상태가 요구하는 것이 서로를 배제하기 때문입니다.

  • 선택지: 튜토리얼은 갈림길을 만들지 않습니다. 아직 고를 능력이 없는 사람에게 선택지를 주면 그 자리에서 멈춥니다. 반대로 하우투는 갈라져야 합니다. 현실은 조건이 다양하고, 조건별 분기가 없는 가이드는 현장에서 쓸모가 없습니다.
  • 책임: 튜토리얼에서 문제가 생기면 그것은 저자의 잘못입니다. 학습자가 실패하지 않도록 환경을 통제해 두어야 합니다. 하우투에서는 사용자가 자기 상황을 책임집니다.
  • 안전: 튜토리얼은 언제든 처음으로 돌아갈 수 있어야 합니다. 하우투는 그런 보장을 할 수 없습니다. 한 번에 맞춰야 하는 작업이 흔합니다.
  • 설명: Diátaxis는 튜토리얼이 설명할 자리가 아니라고 잘라 말합니다. 이유를 말해 주고 싶은 충동이 가르치는 사람에게 가장 이기기 어려운 유혹이라고도 덧붙입니다. 원문의 표현을 빌리면 가르치는 일의 첫 번째 규칙은 "don't try to teach"입니다.

그래서 튜토리얼 3번 항목에 선택지를 넣는 순간, 그 문서는 두 독자 모두에게 나빠집니다. 공부하는 사람에게는 결정을 강요하고, 일하는 사람에게는 필요한 분기를 다 보여 주지도 않습니다.

레퍼런스에 설명이 스며드는 경로

나머지 두 모드 사이에서도 같은 일이 일어나는데, 이쪽은 훨씬 조용합니다. Diátaxis는 그 경로를 구체적으로 짚습니다. 레퍼런스에 예제를 넣는 것 자체는 정당합니다. 문제는 예제가 재미있어서, 쓰다 보면 왜 이렇게 되는지 그리고 이렇게 하면 어떻게 되는지로 자꾸 번져 나간다는 데 있습니다.

결과는 양쪽 손해입니다. 레퍼런스는 곁길에 가려 찾기 어려워지고, 설명은 남의 집에 얹혀 있느라 제대로 펼쳐지지 못합니다. 판정 기준은 다시 하나입니다. 이것은 일하는 도중에 펼쳐 보는 것인가, 아니면 일에서 한 발 물러나 생각할 때 필요한 것인가.

레퍼런스인지 설명인지 헷갈릴 때 쓰기 좋은 경험칙도 있습니다. 지루하고 기억에 남지 않으면 레퍼런스일 가능성이 높고, 목록과 표로 정리되는 것도 대개 레퍼런스입니다. 반대로 산책하면서 누가 물어봤을 때 답이 될 만한 이야기면 설명입니다.

이번 주에 할 수 있는 것 — 한 문단, 한 커밋

Diátaxis의 작업 방식은 큰 그림을 그리지 말라는 쪽입니다. 계획을 세우고 한꺼번에 옮기는 대신 다음 네 단계를 반복하라고 말합니다.

  1. 아무거나 고른다. 문제를 찾아 헤매지 말고 지금 열려 있는 파일, 방금 읽은 페이지를 봅니다. 없으면 무작위로 고릅니다.
  2. 따져 본다. 페이지보다 작을수록 좋습니다. 문단 하나, 문장 하나여도 됩니다. 이것은 어떤 필요를 위한 것인가, 그 필요를 얼마나 잘 채우는가, 무엇을 더하거나 옮기거나 지우면 나아지는가.
  3. 하나만 정한다. 지금 당장 개선이 되는 다음 행동 하나를 고릅니다.
  4. 하고 끝낸다. 그 하나를 하고 바로 커밋하거나 배포합니다. 더 해야 한다고 느끼지 않습니다.

우리 팀에 옮긴다면 이렇게 시작할 수 있습니다. 이번 주에 가장 많이 열린 문서 하나를 열고, 문단마다 앞의 나침반 두 질문을 던져 태그를 답니다. 태그가 두 종류 이상 나온 문서가 있다면 그중 하나만 골라 다른 문서로 옮기고, 있던 자리에는 링크만 남깁니다. 이때 옮겨 갈 문서가 아직 없다면 빈 폴더를 만들지 말고 문서 한 개를 만듭니다. 이 차이가 앞에서 말린 그 실수를 피하는 지점입니다.

문서가 끝나지 않는다는 사실은 바뀌지 않습니다. Diátaxis는 문서를 자라는 식물에 빗대면서, 끝나지는 않지만 매 단계마다 완결되어 있을 수는 있다고 말합니다. 이번 주에 문단 하나를 옮긴 문서도 그 상태에서 완결되어 있습니다.

정리와 출처

한 줄로 줄이면 이렇습니다. Diátaxis는 문서를 분류하는 규칙이 아니라, 한 조각의 글이 누구의 어떤 상태를 섬기는지 묻는 규칙입니다. 폴더 네 개는 그 질문을 대신해 주지 않습니다.

Why Diátaxis Gets Mistaken for Four Folders — And Why Two Modes in One Page Collapse

If you have ever opened a tutorial and closed the tab thirty minutes later

Suppose you open the official tutorial for a library you are using for the first time. Item 1 has you install it. Item 2 has you run the example. So far so good. Then item 3 suddenly begins with "this value can be configured in three ways, and in production the second is recommended." You are handed three options while you have no idea which of the three to pick. Item 4 brings two paragraphs on internal mechanics, and item 5 returns to commands.

This document contains no false information. The sentences are perfectly fine. And yet the reader closes the tab after about thirty minutes. The route by which the documentation team learns this is usually feedback saying "the docs are lacking," and what they do after receiving that feedback is usually to add more content. Then the next person closes the tab after twenty-five minutes.

Creating four folders is not adoption

What named this problem is Diátaxis. It divides documentation into four kinds: tutorial, how-to guide, reference, and explanation. It is widely known and widely cited, but adoption in an actual team generally stops right here. Create four folders in the docs repository, move the existing documents under them, done.

Yet the people who made the framework explicitly warn against this approach. The Diátaxis workflow document says you do not need to divide your documentation into four sections when you start, and it nails the point down about creating four empty sections with nothing in them: do not. Structure is something that appears later as a result of improvement, not something imposed first in order to improve. The author expresses this by saying Diátaxis changes the structure of documentation from the inside out.

The reason there are four is that there are two axes

Why exactly four matters. If there is no reason it is not three or five, then this is merely a convenient classification, and a convenient classification is no help at all in front of an ambiguous document.

The foundational Diátaxis document places the person using a skill on two axes. One is action versus cognition. Any skill has both practical knowledge about what to do and theoretical knowledge about what is true. The other is acquisition versus application. A person is either in the middle of acquiring a skill, or in the middle of using a skill already acquired. You can restate that as the studying state and the working state.

Since the two axes are independent, there are necessarily four quadrants. The need to learn is served by the tutorial, the need to accomplish a goal by the how-to, the need for information by reference, and the need to understand by explanation. Four is not an arbitrarily chosen number; it is the minimum count that covers the territory without remainder.

The compass — asking two questions of a single paragraph

The map is easy to remember, but in front of an ambiguous document intuition is frequently wrong. So Diátaxis provides a separate decision table called the compass. There are only two things to ask.

What this content addressesThe state the user is in right nowThen this is
ActionAcquisition (studying)Tutorial
ActionApplication (working)How-to guide
CognitionApplication (working)Reference
CognitionAcquisition (studying)Explanation

The important thing is that this table can be used at the paragraph level, not just at the document level. In fact Diátaxis recommends applying it down to the level of sentences and words. Put item 3 of the tutorial we saw earlier into this table and the answer comes out immediately. The part listing three configuration methods addresses cognition and faces a person who is working, so it is reference. The rationale for the production recommendation is cognition facing a person who is studying, so it is explanation. Three modes were living inside one document.

The most common confusion happens between tutorial and how-to

Diátaxis points out that the most common confusion in software documentation is the confusion between tutorial and how-to. The reason is simple: the two look almost identical. Both present numbered steps, both promise success if you follow them in order, and both are useless to a reader who does not move their hands.

The difference is not in the form but in the need being served. A tutorial serves someone who is studying; a how-to serves someone who is working. A second misconception that often comes up here is the split where tutorials are basic and how-to guides are advanced, and this is wrong too. The original text says a how-to can and should cover elementary procedures, and conversely that a demanding tutorial for a highly skilled person is possible. The dividing line is not difficulty but whether the reader is studying or working.

The two states demand opposite things

This is where the reason mixing collapses comes from. What the two states demand is mutually exclusive.

  • Choices: a tutorial does not create forks. Give options to someone who is not yet able to choose and they stop right there. Conversely a how-to must branch. Reality has varied conditions, and a guide with no branches by condition is useless in the field.
  • Responsibility: if something goes wrong in a tutorial, that is the author's fault. You must have controlled the environment so the learner cannot fail. In a how-to, the user is responsible for their own situation.
  • Safety: a tutorial must let you return to the beginning at any time. A how-to cannot make that guarantee. Work that has to be got right the first time is common.
  • Explanation: Diátaxis says flatly that a tutorial is not the place to explain. It adds that the urge to tell people why is the hardest temptation for a teacher to resist. Borrowing the original wording, the first rule of teaching is "don't try to teach."

So the moment you put options into item 3 of a tutorial, that document gets worse for both readers. It forces a decision on the person studying, and it does not even show all the branches the person working needs.

The path by which explanation seeps into reference

The same thing happens between the other two modes, and on this side it is far quieter. Diátaxis traces the path concretely. Putting examples into reference is legitimate in itself. The problem is that examples are fun, and as you write them you keep spreading into why it comes out this way and what happens if you do it that way.

The result is a loss on both sides. The reference becomes hard to search because it is buried in detours, and the explanation cannot unfold properly because it is lodging in someone else's house. The criterion is once again a single one: is this something you open in the middle of doing the work, or something you need when you step back from the work to think?

There is also a good rule of thumb for when you cannot tell reference from explanation. If it is boring and does not stick in the memory, it is probably reference, and things that organize into lists and tables are usually reference too. Conversely, if it is the kind of thing that would make a good answer if someone asked you while out on a walk, it is explanation.

What you can do this week — one paragraph, one commit

The Diátaxis way of working is on the side of not drawing the big picture. Instead of making a plan and moving everything at once, it says to repeat these four steps.

  1. Pick anything. Do not go hunting for problems; look at the file that is open right now, the page you just read. If there is nothing, pick at random.
  2. Weigh it up. Smaller than a page is better. One paragraph, or even one sentence, is fine. What need is this for, how well does it fill that need, and what could be added, moved, or deleted to make it better?
  3. Choose exactly one thing. Pick the single next action that constitutes an improvement right now.
  4. Do it and be done. Do that one thing and commit or deploy right away. Do not feel you have to do more.

If you bring it into your own team, you could start like this. Open the single document that was opened the most this week, and put the compass questions above to every paragraph, tagging each one. If a document ends up with more than one kind of tag, pick just one of them, move it into another document, and leave only a link where it was. If the document to move it into does not exist yet, do not create an empty folder — create one document. This difference is exactly where you avoid the mistake that was warned against earlier.

The fact that documentation never ends does not change. Diátaxis likens documentation to a growing plant, saying that it is never finished but can be complete at every stage. A document where you moved a single paragraph this week is complete in that state.

Summary and sources

Reduced to one line: Diátaxis is not a rule for classifying documents but a rule for asking whose state, and which state, a single piece of writing serves. Four folders will not ask that question for you.