분류 체계: 네 개의 사분면, 네 개의 구성 유형
docs.optimism.io의 문서 페이지에는 네 가지 Diátaxis 사분면 값 중 하나, 즉tutorial, how-to, reference, explanation 중 하나를 값으로 갖는 diataxis: frontmatter 키가
있습니다. 이 분류 체계는 완결되어 있으며 확장되지 않습니다. 아래의 구성 유형(composed type)은
사분면의 조합이지 새로운 사분면이 아니며, diataxis: 값으로 사용되지 않습니다.
구성 유형은 diataxis:와 함께 사용하는 두 번째 선택적 frontmatter 키인 content-type:으로
선언합니다. 이 키는 게시된 사양마다 하나씩, 정확히 네 가지 값을 가집니다.
이것이 분기(fork)가 아닌 확장으로 유지되도록 하는 규칙은 다음과 같습니다.
content-type:은diataxis:를 대체하지 않습니다. 무언가를 문서화하거나, 지시하거나, 설명하는 모든 페이지는 사분면 태그를 유지합니다. 허용되는 유일한 생략은content-type: router-landing입니다. 순수한 라우터에는 분류할 고유한 문서 모드가 없으므로content-type:만 포함하고diataxis:키는 포함하지 않습니다. 라우터에 설명이나 지시 콘텐츠가 추가되면 더 이상 라우터가 아니므로 다시 분류하십시오.content-type:값은 이 네 가지만 존재합니다. 다섯 번째 값을 제안하려면 일반적인 문서 검토를 거쳐 이 페이지를 수정하고 해당 사양을 게시해야 합니다.- 네 가지 기본 유형의 페이지에는
content-type:을 전혀 포함하지 않습니다. 일반적인 how-to는 그냥diataxis: how-to입니다. - 구성 유형을 위해
keywords.config.yaml을 확장하지 않습니다. 구성 유형은 위 표의 각 행에 따라 페이지 frontmatter에서만 선언합니다.
공지 메타데이터
공지는 독자의 준비가 필요한 업그레이드, 지원 중단 또는 기타 변경에 대한 기한이 있는 운영 콘텐츠입니다. 독자에게 가장 필요한 것은 특정 변경에 대한 권위 있는 정보이므로, 공지에는diataxis: reference를 사용합니다.
추가 메타데이터 키인 content_type: notice(밑줄 사용)는 공지 인덱스와 사이트 검색을 위해 페이지의
운영 목적과 생애 주기를 표시합니다. 이는 다섯 번째 사분면이나 구성 유형을 만들지 않습니다.
content-type: 키(하이픈 사용)는 여전히 위의 네 가지 구성 유형 값으로 제한됩니다.
페이지가 다음 질문에 모두 답해야 하는 경우 공지를 사용하십시오.
- 무엇이 왜 변경됩니까?
- 어떤 페르소나가 영향을 받으며, 각 페르소나에게 무엇이 중단되거나 호환성을 유지합니까?
- 영향을 받는 각 독자가 전환 전에 해야 할 일은 무엇입니까?
- 변경은 언제, 어떻게 적용됩니까?
How-to 가이드 vs. 튜토리얼 vs. 솔루션 가이드
이 세 유형은 모두 실행 지향적이어서 혼동하기 쉽습니다. 차이점은 시작 상태, 범위, 그리고 단계를 누가 소유하는지에 있습니다.
빠른 판별 기준:
- 실제 작업을 시작하기 전에 페이지에서 환경을 설치하거나 구성해야 한다면 튜토리얼입니다.
- 페이지의 단계가 자체적인 것, 즉 독자가 하나의 구성 요소에서 실행하는 복사-붙여넣기 가능한 명령이라면 how-to 가이드입니다.
- 페이지의 주된 역할이 목표를 향해 다른 페이지를 순서대로 배열하고 그 과정에서 옵션 간 결정을 내리는 것이라면 솔루션 가이드입니다. 연결된 페이지의 단계를 다시 서술하기 시작하는 솔루션 가이드는 이중 소스 금지 원칙을 위반하는 것이므로, 다시 서술한 부분을 삭제하고 링크로 대체하십시오.
설명 vs. 학습 단위
두 유형 모두 이해 지향적입니다. 차이점은 독자가 누구이며 페이지가 무엇을 전제할 수 있는지에 있습니다.
빠른 판별 기준:
- 페이지를 탐색 그룹에서 제거해도 완전히 이해할 수 있다면 설명입니다.
- 페이지가 “이전 단계에서…”로 시작하거나 순서의 N번째 위치에서만 의미가 있다면 학습 단위입니다.
- 순서를 바꾸기 위해 설명을 트랙으로 복사하려 한다면 멈추십시오. 학습 단위는 링크하고 프레이밍할 뿐 절대 복제하지 않습니다. 대신 기존 페이지에 프레이밍 헤더를 추가하십시오 (학습 단위 사양 참조).