기술 문서를 어떤 순서로, 어떤 형식으로 써야 하는지는 개발자보다 문서 작성자를 더 오래 괴롭히는 문제다. 웹 개발자 다니엘레 프로치다(Daniele Procida)가 만든 Diátaxis는 이 문제를 "문서에는 근본적으로 네 가지 종류가 있다"는 명제로 정리한 체계다. 튜토리얼(tutorial), 하우투 가이드(how-to guide), 레퍼런스(reference), 설명(explanation)이 그 네 가지이며, Diátaxis는 이들을 임의로 나열하지 않고 두 개의 축으로 교차시켜 배치한다. Cloudflare 개발자 문서, Gatsby, Vonage가 각자 문서 구조를 다시 짤 때 이 틀을 기준으로 삼았다고 공개적으로 밝힌 것도 이 체계가 실무에서 자주 검증됐기 때문이다.
네 가지 문서는 어떤 기준으로 나뉘는가
Diátaxis는 문서를 나누는 기준으로 두 가지 질문만 쓴다. 첫째, 이 내용이 사용자의 "행동(action)"에 관한 것인가, "인지(cognition)"에 관한 것인가. 둘째, 사용자가 지금 스킬을 "습득(acquisition)"하는 중인가, 이미 가진 스킬을 "적용(application)"하는 중인가. 이 두 질문의 답을 교차하면 네 칸이 만들어지고, 각 칸에 정확히 하나의 문서 유형이 대응한다. 행동+습득은 튜토리얼, 행동+적용은 하우투 가이드, 인지+적용은 레퍼런스, 인지+습득은 설명이다. Diátaxis는 이 교차표를 "나침반(compass)"이라 부르며, 지금 쓰고 있는 문서가 어느 칸에 속하는지 헷갈릴 때 이 두 질문으로 되돌아가라고 안내한다.
네 유형은 서로 다른 질문에 답한다
Diátaxis 공식 문서는 네 유형의 차이를 "답하는 질문"으로 요약한다. 튜토리얼은 "가르쳐 줄 수 있나요?"에 답하는 학습 경험이고, 하우투 가이드는 "어떻게 하나요?"에 답하는 목표 지향적 안내다. 레퍼런스는 "이것이 무엇인가요?"에 답하는 정보 중심 서술이고, 설명은 "왜 그런가요?"에 답하는 이해 지향적 논의다. 요리책에 비유하면 튜토리얼은 아이에게 요리를 가르치는 과정, 하우투 가이드는 요리책의 레시피, 레퍼런스는 식품 포장지 뒷면의 성분표, 설명은 음식의 역사를 다루는 글에 해당한다. 이 네 축을 한 표에 놓으면 지금 쓰려는 문서가 어느 목적에 봉사해야 하는지가 분명해진다.
하우투 가이드는 왜 도구가 아니라 목표를 따라 써야 하는가
Diátaxis가 가장 강하게 지적하는 실패 패턴은 하우투 가이드를 사용자의 목표가 아니라 도구의 기능을 따라 쓰는 것이다. 공식 문서는 "물을 끄려면 수도꼭지를 시계 방향으로 돌리세요" 같은 문장을 예로 든다. 이런 문장은 안내처럼 보이지만 실제로는 그 분야에서 일하는 사람이라면 이미 알고 있을 당연한 사실만 나열할 뿐, 사용자가 실제로 필요한 정보인 "특정 목적에 얼마나 세게, 얼마나 오래 물을 틀어야 하는가"에는 답하지 않는다. 소프트웨어 문서에서도 마찬가지로, 버튼을 누르는 절차만 나열하고 그 설정이 실제 어떤 상황에 맞는지는 설명하지 않는 하우투 가이드가 흔하다. Diátaxis는 하우투 가이드가 다루는 범위를 도구의 기능 목록이 아니라 사용자가 실제로 마주치는 프로젝트와 문제로 정의해야 한다고 못박는다.
튜토리얼과 설명이 자주 부실한 이유
Diátaxis는 네 유형 중 튜토리얼과 설명이 실무에서 가장 소홀히 다뤄진다고 짚는다. 튜토리얼은 교사와 학생의 계약과 같아서, 학생이 실수해도 책임은 전부 교사(문서)에게 있다. 그런데 문서 안의 교사는 학생을 직접 보고 교정해 줄 수 없기 때문에, 글로만 그 역할을 대신해야 하는 근본적인 어려움이 있다. 게다가 제품이 빠르게 바뀌면 튜토리얼 전체를 처음부터 끝까지 다시 손봐야 하는 경우가 많아, 유지 비용이 다른 문서 유형보다 훨씬 크다. 설명은 반대로 범위를 정하기 어렵다는 문제를 갖는다. 튜토리얼·하우투 가이드·레퍼런스는 각각 배워야 할 것, 달성해야 할 작업, 서술해야 할 기능이라는 명확한 경계가 있지만, 설명은 "왜 그런가"라는 열린 질문에서 시작하기 때문에 어디서 멈춰야 할지 저자가 직접 판단해야 한다. 그 결과 많은 문서에서 설명은 독립된 섹션 없이 다른 문서 곳곳에 흩어진 채로 방치된다.
출처: Diátaxis, "A systematic approach to technical documentation authoring"