Diátaxis - 기술 문서 작성을 위한 체계적 접근법

Diátaxis는 문서 사용자의 서로 다른 요구를 기준으로 기술 문서의 내용/형식/구조를 설계하는 체계적 접근법 사용자의 요구를 튜토리얼/방법 안내서/기술 참조/설명 네 가지로 구분하고, 각 문서 유형의 역할과 관계에 따라 전체 문서 체계를 구성함 무엇을 작성할지에 해당하는 콘텐츠, 어떻게 작성할지에 해당하는 문체, 어디에 배치할지에 해당하는 정보 구조 문제를 함께 다룸 가볍고 이해하기 쉬우며 특정 구현 방식에 제약을 두지 않아, 문서 작성자와 유지보수자가 기존 문서에 점진적으로 적용할 수 있음 수백 개의 문서화 프로젝트에 도입됐으며 Vonage/Gatsby/Cloudflare는 내부 문서 품질, 자료 탐색성, 정보 구조의 명확성이 개선됐다고 평가함 Diátaxis의 기본 구조 Diátaxis는 기술 문서를 작성하는 방법인 동시에 문서를 바라보는 사고 체계임 문서 사용자의 요구를 체계적으로 이해하고, 그 요구로부터 콘텐츠/구조/형식에 대한 작성 원칙을 도출함 문서 자체도 사용자의 요구 구조를 중심으로 조직하도록 제안함 네 가지 문서 유형 튜토리얼 은 사용자가 학습 경험을 따라가며 새로운 능력을 얻도록 안내하는 문서 방법 안내서 는 사용자가 특정 목표나 과제를 완수하도록 돕는 문서 기술 참조 는 제품/시스템의 구성과 동작에 관한 정확한 정보를 제공하는 문서 설명 은 개념과 맥락을 이해하고 지식을 연결하도록 돕는 문서 네 유형은 서로 대체되는 형식이 아니라, 각기 다른 사용자 요구를 충족하면서 체계적으로 연결됨 해결하려는 문서화 문제 콘텐츠: 어떤 정보를 작성해야 하는지 결정함 문체와 형식: 해당 문서 유형에 맞게 정보를 어떻게 전달할지 결정함 정보 구조: 서로 다른 문서를 어떤 관계와 계층으로 배치할지 결정함 문서 작성자가 자신의 작업을 판단할 수 있는 능동적인 품질 원칙을 제공함 작성자와 유지보수자를 위한 특성 문서 사용자뿐 아니라 문서를 작성하고 관리하는 사람에게도 적용됨 가볍고 이해하기 쉬우며 실제 작업에 곧바로 적용하기 쉬움 특정 문서 도구/플랫폼/구현 기술을 요구하지 않음 새로운 문서를 분류하거나 기존 문서의 위치와 목적을 재검토할 때 판단 기준으로 사용할 수 있음 적용을 시작하는 방법 짧은 입문 문서를 읽고 실제 문서에 적용하는 방식을 권장함 Start here 에서 기본 개념을 익힐 수 있음 구체적인 적용 자료로 다음 항목을 제공 Applying Diátaxis The compass Workflow ...