Diátaxis 문서화 프레임워크

• Diátaxis는 사용자의 요구를 바탕으로 기술 문서의 콘텐츠·형식·구조를 설계하는 접근법임
• 문서를 튜토리얼·사용법 가이드·기술 참조·설명의 네 유형으로 구분하고, 각 유형의 관계에 따라 구성함
• 무엇을 쓸지뿐 아니라 어떻게 쓰고 조직할지까지 아우르며 콘텐츠·스타일·아키텍처 문제를 함께 다룸
• 이해하고 적용하기 쉬우며 특정 구현 방식을 강제하지 않아, 작성자와 유지관리자가 문서 품질을 판단하는 기준으로 활용할 수 있음
• 수백 개 문서화 프로젝트가 원칙을 도입했으며, Vonage·Gatsby·Cloudflare는 문서 품질과 탐색성·정보 구조 개선에 활용함

사용자 요구에 따른 네 가지 문서 유형

• Diátaxis는 서로 다른 사용자 요구에 대응하도록 문서를 네 가지 형식으로 구분함

  • 튜토리얼(tutorials)

  • 사용법 가이드(how-to guides)

  • 기술 참조(technical reference)

  • 설명(explanation)

    • 네 유형을 체계적인 관계로 배치하고, 사용자 요구의 구조를 중심으로 문서 전체를 조직하도록 권장함

적용과 품질 판단

• 간략한 입문서를 읽은 뒤 실제 문서에 적용하는 방식으로 시작할 수 있음
• 각 유형의 기반이 되는 요구는 Diátaxis의 이론과 원칙을 통해 더 깊이 이해할 수 있음
• 특정 구현 제약을 부과하지 않으면서 유지관리자가 자신의 작업을 판단할 수 있는 능동적인 품질 원칙을 제공함

실제 도입 사례

• Vonage는 사용자가 선호하고 기여자가 내용을 추가하기 쉬운 고품질 내부 문서 구축에 활용함
• Gatsby는 오픈소스 문서를 재구성하면서 네 영역을 기준으로 문서 유형별 사용자 목표의 우선순위를 정함
  • 필요한 자료를 사용자가 적시에 더 쉽게 찾을 수 있도록 문서 구조를 개선함
• Cloudflare는 개발자 문서를 재설계할 때 Diátaxis를 정보 아키텍처 기준으로 사용함
  • 새 콘텐츠를 어디에 배치할지 불분명할 때 프레임워크를 참조함
  • 그 결과 독자와 기여자 모두에게 이전보다 명확한 문서 구조를 구축함