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

• 튜토리얼을 열고 30분 만에 창을 닫은 적이 있다면
• 네 개의 폴더를 만드는 것은 적용이 아닙니다
• 네 개인 이유는 두 개의 축 때문입니다
• 나침반 — 문단 하나에 두 질문만 던지기
• 가장 흔한 혼동은 튜토리얼과 하우투 사이에서 납니다
• 두 상태는 정반대의 것을 요구합니다
• 레퍼런스에 설명이 스며드는 경로
• 이번 주에 할 수 있는 것 — 한 문단, 한 커밋
• 정리와 출처

튜토리얼을 열고 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는 문서를 분류하는 규칙이 아니라, 한 조각의 글이 누구의 어떤 상태를 섬기는지 묻는 규칙입니다. 폴더 네 개는 그 질문을 대신해 주지 않습니다.

• Diátaxis 공식 사이트 — 프레임워크 본문. 아래 항목은 모두 이 사이트의 문서입니다.
• Foundations — 행동과 인지, 습득과 적용이라는 두 축, 그리고 사분면이 넷인 이유
• The compass — 두 질문으로 판정하는 표
• The difference between a tutorial and how-to guide — 선택지·책임·안전·설명에 대한 대비, 기초와 고급이라는 오해
• The difference between reference and explanation — 설명이 레퍼런스로 스며드는 경로와 경험칙
• Diátaxis as a guide to work — 빈 섹션을 만들지 말라는 경고, 네 단계 작업 루프, 완결과 종료의 구분
• Tutorials — 가르치려 들지 말라는 원칙과 설명이라는 유혹
• 문서 원문은 evildmp/diataxis-documentation-framework 저장소에서 그대로 읽을 수 있습니다. 이 글의 인용과 요약은 그 저장소의 원문을 직접 확인한 것입니다.