docs
실제 사람이 읽고 싶은 문서를 작성하세요. 짧고, 평이하게, 실제 작업을 수행하려는 사람을 중심으로 구성하세요.
"기능 X에 대한 문서"가 목표가 아닙니다. "누군가가 X를 사용하여 Y를 수행하도록 돕는 것"이 목표입니다.
두 단계로 작업합니다. 먼저 스토리를 계획합니다: 누가 이 글을 읽는지, 그들이 원하는 것이 무엇인지, 페이지는 몇 개여야 하는지. 그런 다음 작성합니다.
계획은 비공개가 아닙니다. 사용자는 독자를 확인해야 하며, 페이지가 작성되기 전에 어조를 선택해야 합니다.
문서 찾기
→ 주변 문서 읽기
→ 1단계: 독자 + 페이지
→ 페르소나 게이트 (채팅에 독자 목록을 작성한 후 중지)
→ 어조 게이트 (채팅에 어조를 작성한 후 중지) [페이지 작성 시]
→ simple-english + i-have-adhd 로드 [페이지 작성 시]
→ 2단계: 작성
기능 계획 내의 문서 영향 목록은 여전히 페르소나 게이트를 실행합니다. 페이지가 실제로 작성될 때까지 어조 게이트를 실행하거나 작성 기술을 로드하지 않습니다.
실행 시기
문서는 코드와 함께 제공됩니다. 요청받았을 때뿐만 아니라 다음 세 가지 시점에 이 스킬을 실행하세요.
- 누군가가 문서를 요청했습니다. 작성하세요.
- 저장소에서 기능이나 변경 사항을 계획 중입니다. 계획이 완료되기 전에 새 문서와 업데이트가 필요한 문서를 나열하세요. 이 문서 영향 목록은 코드 변경과 마찬가지로 계획의 일부입니다. 각 페이지의 독자를 명시하세요.
- 구현을 마무리하는 중입니다. 작업 완료를 선언하기 전에 해당 문서를 작성하거나 업데이트하세요. 문서 변경 없이 동작 방식이 변경되는 것은 완료된 것이 아닙니다.
최종 페이지에 필요한 스킬
simple-english와 i-have-adhd는 필수입니다. 이 스킬들은 계획 채팅이 아닌 문서 페이지에 적용됩니다.
페이지 콘텐츠를 작성하기 직전에 두 스킬을 모두 로드하세요. 이 도구 모음에 Skill 도구가 있으면 사용하세요. 없으면 로컬 스킬 디렉토리에서 각 스킬의 SKILL.md를 읽으세요. 해당 스킬의 내용을 기억으로 페이지를 작성하지 마세요.
둘 중 하나라도 없으면 사용자에게 알리고 중지하세요. 해당 스킬 없이 페이지를 작성하지 마세요.
구성 방식:
- 이 스킬은 페이지의 대상, 페이지 분할, 문제-해결 구조, 보여주기 말고 말하지 않기, 이력 누출 없음, 금지된 글리프, 그리고 이웃 페이지 구조를 결정합니다.
simple-english는 문장을 결정합니다. 실용 모드(pragmatic mode)를 사용하세요. 페이지 완료를 선언하기 전에 자체 점검을 실행하세요.i-have-adhd는 페이지의 형태를 결정합니다: 첫 번째 행동 먼저, 번호가 매겨진 단계, 최대 5개의 목록(필수와 나중으로 분할하거나 페이지 분할), 서문 없음, 마지막에 눈에 띄는 성취.
이 스킬에서 i-have-adhd가 로드될 때, 페이지에만 적용하세요. 세션의 나머지 부분을 ADHD 모드로 전환하지 마세요. i-have-adhd의 지속성 섹션은 여기에 적용되지 않습니다.
먼저 문서 찾기
무엇이든 작성하기 전에 문서의 위치를 찾으세요.
- docs 폴더를 찾으세요.
docs/를 먼저 확인하고, 그다음documentation/,content/docs/,site/,website/docs/를 확인하세요. - 아무것도 없나요? 사용자에게 문서가 어디에 있어야 하는지 물어보세요. 추측하지 말고 직감에 따라 폴더를 만들지 마세요.
- 새 콘텐츠가 속할 위치 근처의 기존 페이지 2~3개를 열어보세요. 복사, 구조, 머리말 필드, 구성 요소를 위해 읽으세요. 어조 게이트의 후보로 보이는 어조를 기록하세요. 아직 채택하지 마세요.
- 사이트에서 이미 사용 중인 구성 요소(단계, 탭, 콜아웃, 카드, 아코디언, 코드 그룹 등)를 기록하세요. 사이트마다 다른 구성 요소가 있습니다.
- 해당 구성 요소를 사용하여 스토리를 전달하세요. 사이트에 단계 구성 요소가 있으면 연습에 사용하세요. 탭이 있으면 프레임워크 변형에 사용하세요. 아무것도 없으면 일반 마크다운을 사용하세요. 사이트에 없는 구성 요소를 절대 만들어 내지 마세요.
작성하려는 페이지와 유사한 페이지가 없으면 찾을 수 있는 가장 가까운 페이지를 읽고 일치시키세요.
"이웃 페이지 일치"가 포함하는 것과 포함하지 않는 것
이웃 페이지 일치는 복사, 구조, 머리말, 구성 요소에 관한 것입니다: 제목이 문장형 대문자인지, 섹션에 얼마나 많은 설정이 있는지, 어떤 구성 요소가 연습을 전달하는지, 코드 샘플이 어떻게 소개되는지, 머리말 필드가 무엇인지.
이는 어조 게이트를 대체하지 않습니다. 이웃 페이지는 기본값을 제안할 수 있습니다. 사용자를 대신하여 결정할 수는 없습니다.
이는 이웃 페이지의 나쁜 습관을 복사하는 허가가 아닙니다. 금지됨의 모든 내용과 이 스킬의 모든 규칙은 주변 페이지가 무엇을 하든 작성하는 콘텐츠에 여전히 적용됩니다. 엠 대시로 가득 찬 기존 페이지가 하나 더 있다고 해서 한 개 더 허용되는 것은 아닙니다.
따라서: 이 스킬이 명시하는 규칙에 대해 "다른 페이지도 그렇게 하니까 나도 그렇게 할게"라고 추론하지 마세요. 기존 페이지가 규칙을 위반하고 있고 전체 세트를 정리해야 한다고 생각되면 사용자에게 제기할 별도의 정리 작업이지, 조용히 위반 사항을 일치시켜 해결할 문제가 아닙니다.
1단계: 스토리 계획
콘텐츠를 한 글자도 쓰기 전에 하세요.
- 누가 이것을 읽는지, 그리고 각각 무엇을 원하는지 나열하세요. React SPA에서 구축하는 사람, 서버 렌더링 앱을 사용하는 사람, 빠른 데모를 원하는 사람, 내부를 확장하는 사람. 첫 번째 독자에서 멈추지 마세요.
- 독자별로 하나의 사용자 스토리를 작성하세요: "X로서, Y를 원합니다, 그래서 Z를 할 수 있습니다."
- 스토리를 페이지로 전환하세요. 하나의 여정은 하나의 페이지입니다. 다른 여정은 다른 페이지입니다. 세 개의 실제 여정이 있는 기능은 아마도 짧은 개요 페이지와 함께 세 페이지이지, 하나의 거대한 페이지가 아닙니다.
- 모든 독자에게 경로가 있는지 확인하세요. 페이지가 없는 독자는 계획의 구멍입니다. 그들을 위한 페이지나 경로를 추가하세요.
페이지 분할은 이 단계에서 나옵니다. 건너뛰지 마세요.
게이트: 페르소나 보여주기
<하드-게이트> 사용자는 채팅에서 목록을 볼 수 있어야 합니다. 생각, 할 일, 묻힌 계획, 또는 질문 도구 안에만 독자를 나열하는 것은 이 게이트를 통과하지 못한 것입니다.
질문 도구(AskQuestion, ask_user_question 및 유사한 형식)는 사용자가 읽는 채팅에 페이로드를 표시하지 않습니다. 해당 도구 중 하나만 호출하는 턴은 이 게이트를 통과하지 못합니다. 사용자는 볼 수 없는 목록을 확인하라는 요청을 받습니다.
4단계 후에 일반 채팅 메시지를 작성하세요. 질문 도구도 호출되는 경우에도 메시지 본문은 필수입니다. 메시지에는 다음이 포함됩니다:
- 각 독자, 사용자가 훑어볼 수 있는 자체 짧은 블록:
- 독자의 이름.
- 하나의 사용자 스토리: "X로서, Y를 원합니다, 그래서 Z를 할 수 있습니다."
- 그들을 위해 작성할 페이지.
- 같은 메시지에 작성된 하나의 질문: 확인, 독자 제거, 또는 추가.
질문 도구는 선택 사항입니다. 해당 목록이 채팅 메시지에 이미 있는 경우에만 호출하세요. 도구는 짧은 선택(확인, 제거 또는 추가)만 묻습니다. 독자 이름, 스토리 또는 페이지를 도구 안에 넣지 마세요. 도구가 턴의 유일한 출력이 될 경우 호출하지 마세요. 대신 메시지를 작성하세요.
그런 다음 하나의 경로를 선택하세요:
기본값: 중지. 이 메시지는 전체 턴입니다. 턴을 종료하세요. 파일을 작성하지 마세요. 2단계를 시작하지 마세요. 사용자가 반대하지 않는 한 진행할 것이라고 말하지 마세요.
대기 건너뛰기: 같은 턴에서 계속. 다음 중 하나가 참인 경우에만 이 경로를 사용하세요:
- 이 대화에 이미 이 페르소나 목록에 대한 사용자의 확인이 있습니다.
- 사용자가 "합리적인 기본값 사용", "그냥 작성", 또는 "질문하지 마"라고 말했습니다. 여전히 이 턴에서 목록을 보여준 후 계속하세요.
- 변경 사항이 사소한 복사 편집인 경우: 오타, 깨진 링크, 코드 펜스 언어, 또는 사실 수정. 새 페이지, 새 섹션, 여정 재작성 없음.
이 경로에서는 턴을 종료하지 마세요. 목록을 보여준 후(또는 사소한 복사 편집 후, 목록 없이) 다음 단계로 계속하세요.
다음은 건너뛰기에 해당하지 않습니다:
- "독자는 명백합니다."
- "사용자가 문서를 요청했으므로 질문을 원하지 않습니다."
- "이미 계획에 이름을 지정했습니다."
- "독자가 한 명뿐입니다."
- "이것은 기능 구현의 일부이므로 계속 진행하세요."
- "질문 도구가 그들에게 목록을 보여줄 것입니다." 그렇지 않습니다. 목록은 채팅에 있어야 합니다.
문서를 작성하는 것이 이 게이트가 존재하는 이유입니다. 건너뛰는 이유가 아닙니다. </하드-게이트>
적을수록 좋다: 분할하고, 채우지 마라
수천 단어를 한 페이지에 강제로 넣지 마세요. 긴 페이지는 답을 숨깁니다.
주제에 여러 각도가 있을 때 각각에 자체 짧은 페이지를 제공하고 연결하세요. 독자는 개요에 도착한 다음 필요한 정확한 것을 클릭합니다.
예시. 도구 인터럽트 기능:
나쁨: 한 페이지
interrupts.md (개요 + 간단한 경우 + 여러 인터럽트 + 사용자 정의, 모두 채워 넣음)
좋음: 연결된 작은 페이지 세트
interrupts/index.md 정의, 사용 시기, 링크
interrupts/basic.md 하나의 인터럽트, 처음부터 끝까지
interrupts/multiple.md 흐름에서 여러 인터럽트
interrupts/custom.md 직접 구축하기
각 페이지는 짧고 한 가지 일을 합니다. 개요가 그것들을 스토리로 엮습니다.
게이트: 어조 묻기
이 게이트는 1단계와 2단계 사이에 있습니다. 페이지를 작성하기 전에 실행하세요. 2단계 안에 중첩시키지 마세요.
<하드-게이트> 이 게이트는 페이지 콘텐츠가 작성되기 전에 실행됩니다. 계획만 있는 문서 영향 목록에 대해서는 실행되지 않습니다.
이웃 페이지는 기본값을 제안할 수 있습니다. 사용자를 대신하여 결정할 수는 없습니다.
일반 채팅 메시지를 작성하세요. 질문 도구도 호출되는 경우에도 메시지 본문은 필수입니다. 메시지에는 다음이 포함됩니다:
- 이웃 페이지에서 유추한 어조를 한 줄로 (얼마나 격식 있는지, 설정이 얼마나 필요한지, 2인칭 사용 여부).
- 같은 메시지에 작성된 하나의 질문: 그 어조 사용, 더 캐주얼하게, 더 격식 있게, 또는 사용자가 다른 것을 지정.
질문 도구는 선택 사항이며 해당 줄이 채팅에 있는 후에 옵니다. 도구는 짧은 선택만 묻습니다. 유추된 어조만 도구 안에 넣지 마세요. 도구만 호출하는 턴은 이 게이트를 통과하지 못합니다.
그런 다음 하나의 경로를 선택하세요:
기본값: 중지. 이 메시지는 전체 턴입니다. 턴을 종료하세요. 페이지 콘텐츠를 작성하지 마세요.
대기 건너뛰기: 같은 턴에서 계속. 다음 중 하나가 참인 경우에만 이 경로를 사용하세요:
- 이 대화에 이미 사용자의 어조 선택이 있습니다. "기존 페이지와 일치"라는 명시적 포함.
- 사용자가 "합리적인 기본값 사용", "그냥 작성", 또는 "질문하지 마"라고 말했습니다. 여전히 유추된 어조를 한 줄로 명시한 후 계속하세요.
- 사소한 복사 편집, 페르소나 게이트와 동일한 예외.
이 경로에서는 턴을 종료하지 마세요. 어조를 명시한 후(또는 사소한 복사 편집 후, 질문 없이) 2단계로 계속하세요.
다음은 건너뛰기에 해당하지 않습니다:
- "이웃 페이지에서 알 수 있습니다."
- "사이트에 이미 음성이 있습니다."
- "참조 페이지의 경우 어조는 중요하지 않습니다."
- "이웃 페이지와 일치시키고 나중에 언급하겠습니다." </하드-게이트>
2단계: 인간처럼 작성하기
페르소나 게이트, 어조 게이트를 통과하고 simple-english와 i-have-adhd가 로드될 때까지 페이지 콘텐츠를 작성하지 마세요.
어조 게이트는 이 위의 제목입니다. 그 게이트를 먼저 실행하세요. 그런 다음 두 스킬을 로드하세요. 그런 다음 작성하세요.
가독성이 다른 모든 것보다 목표입니다.
- 소화하기 쉽게 유지하세요. 텍스트 벽, 거대한 단락 없음. 아이디어를 작은 조각으로 나누세요. 작업을 수행하는 데 필요한 가장 적은 양의 정보를 제공하세요.
- 문장은
simple-english(실용 모드)를 따릅니다. 더 약한 대체물을 인라인으로 사용하지 마세요. - 마크다운을 가볍게 유지하세요. 목록은 괜찮습니다. 모든 줄에 굵은 제목은 아닙니다. 단어가 페이지를 전달하게 하세요.
- 화려한 글리프보다는 일반 ASCII와 일반 키보드 문자를 선호하세요. 사람이 입력하는 방식으로 작성하세요.
- 2인칭, 행동 우선. 독자가 지금 가지고 있는 것과 마지막에 가질 것으로 시작하세요. "이 가이드에서는...을 살펴보겠습니다"와 같은 시작은 하지 마세요. 그냥 시작하세요.
i-have-adhd로 페이지를 구성하세요: 첫 번째 줄은 독자가 할 수 있는 것이고, 여러 단계 작업에는 번호가 매겨지며, 5개보다 긴 목록은 분할되고, 페이지는 눈에 띄는 성취로 끝납니다.
문제로 시작하여 해결하기
모든 페이지는 독자가 찾아온 문제로 열리며, 그들의 언어로, API보다 먼저. 그들이 처한 상황을 명명하세요. 그런 다음 한두 문장으로 기능이 어떻게 해결하는지 말하세요. 그 후에야 기술적인 부분과 코드로 들어가세요.
먼저 문제를 보는 독자는 몇 초 안에 자신이 올바른 페이지에 있는지 알 수 있습니다. API 서명을 먼저 보는 독자는 그것이 무엇을 위한 것인지 역으로 추론해야 합니다.
'방법'의 첫 번째 줄은 다음 행동입니다(i-have-adhd에서). 문제가 여전히 먼저 와서 그들이 올바른 페이지에 있다는 것을 알게 합니다.
나쁨:
useInterrupts()를 호출하고 해석기를 전달하세요. 해석기는 트랜잭션 내에서 대기 중인 각 항목에 대해 한 번 실행됩니다...
좋음:
어떤 도구 호출은 사람의 승인 없이 실행되어서는 안 됩니다: 돈 이동, 데이터 삭제. 인터럽트는 해당 결정을 위해 실행을 일시 중지하고 중단된 지점에서 다시 시작합니다. 승인 뒤에 도구를 게이트하는 방법은 다음과 같습니다:
[코드]
가이드의 순서는 문제, 한 줄 해결책, 그다음 방법(단계, 스니펫, API)입니다. 문제를 몇 문장으로 유지하고 배경 에세이로 만들지 마세요. 코드가 해결 방법을 보여주므로 먼저 산문으로 해결책을 설명하지 마세요.
보여주고, 말하지 마라
한 문장과 코드 블록으로 보여줄 수 있는 것을 네 단락으로 설명하지 마세요. 독자는 산문보다 diff나 스니펫을 더 빨리 이해합니다.
나쁨:
config 객체가 middleware 배열을 어떻게 받아들이는지, 각 슬롯이 무엇을 하는지, 순서가 어떻게 작동하는지 설명하는 세 단락.
좋음:
`middleware` 배열에 미들웨어를 추가하세요. 순서는 위에서 아래로 실행됩니다:
const app = createApp({
middleware: [auth, logging],
})
하나의 잘 실행되는 예제가 설명 한 페이지보다 낫습니다. 모든 코드 샘플은 복사했을 때 실행 가능해야 하며, 격차를 메우기 위해 상상력이 필요하지 않아야 합니다.
목록인 것은 목록으로 만드세요
문장이 두 개 이상의 항목, 옵션, 저장소, 플래그 또는 단계를 다루는 순간 목록이 됩니다. 쉼표와 세미콜론으로 단락에 연결하지 마세요. 글머리 기호 목록을 훑어보는 독자는 1초 안에 항목을 찾습니다. 단락에서는 전체를 읽어야 자신에게 적용되지 않는다는 것을 알 수 있습니다.
판단 기준은 두 개 이상의 사물을 명명하고 각각에 대해 무언가를 말하는 문장입니다. 사물당 하나의 글머리 기호로 자르고 각각 한두 문장으로 만드세요.
나쁨:
각 저장소는 독립적입니다. 필요한 것만 제공하세요. 채팅의 경우: `messages`는 대화 기록용, `runs`는 실행 수명 주기용, `interrupts`는 지속적인 승인용(`runs` 필요), `metadata`는 네임스페이스 키/값 상태용입니다. 생성을 위해: `generationRuns`는 실행 수명 주기용, 그리고 생성된 바이트를 유지하기 위한 `artifacts`와 `blobs`.
좋음:
각 저장소는 독립적이므로 필요한 것만 제공하세요.
채팅의 경우:
- `messages`: 대화 기록.
- `runs`: 실행 수명 주기.
- `interrupts`: 지속적인 승인. `runs` 필요.
- `metadata`: 네임스페이스 키/값 상태.
생성을 위해:
- `generationRuns`: 실행 수명 주기.
- `artifacts`와 `blobs`: 생성된 바이트 유지.
금지됨
이러한 규칙은 어조 게이트나 이웃 페이지 일치에 의해 재정의되지 않습니다.
엠 대시 (—). 당황스러운 일이지만, 절대 사용하지 마세요. 대신 문장을 다시 작성하거나 필요하면 하이픈(-)을 사용하세요. (현대 도구 체인에서 엠 대시를 입력하기 어렵고 HTML 엔티티는 가독성을 해칩니다.) 엔 대시(–)도 동일하게 금지됩니다.
참고 (Note:). 절대 사용하지 마세요. 참고 사항은 일반 텍스트입니다. "참고"는 필요 없습니다. 말하고 싶은 것을 그냥 말하세요. 강조가 필요하면 굵게나 이탤릭을 사용하세요.
학습 목표 (Learning objectives). 절대 사용하지 마세요. 정보 페이지이지 교과서가 아닙니다.
개요 섹션 (Overview sections). 절대 사용하지 마세요. 제목에 "개요"를 사용하면 독자가 훑어볼 수 있을 때 그 아래에 아무것도 없다는 신호입니다. 제목은 관련성을 나타내야 합니다.
이전 (formerly, previously). 절대 사용하지 마세요. 역사 수업이 아닙니다. 함께 설명해야 한다면 현재 이름 뒤에 괄호 안에 예전 이름을 한 번만 넣으세요. 그 외에는 이전 이름을 언급하지 마세요.
교차 참조 (cross-reference). "위 참조"나 "아래 참조"를 사용하지 마세요. 독자는 페이지를 아래로 스크롤할 수도 있고 위로 스크롤할 수도 있습니다. 링크를 걸거나 섹션 제목을 명시하세요.
배경 섹션 (Background sections). 절대 사용하지 마세요. 독자는 배경이 아닌 문제를 위해 왔습니다. 그들이 이미 알고 있는 것을 가정하고, 그들이 모르는 것이 단계를 막는다면 그곳에서 설명하세요.
알려진 제한 사항 (Known limitations). 제목으로 사용하지 말고 기능 설명에서 정직하게 다루세요.
투두 (TODOs). 절대 문서에 남기지 마세요.
면책 조항 (Disclaimers). 표준 안내서에는 절대 사용하지 마세요. 법적 맥락에서 필요하지 않는 한 제거하세요.
부드러운 언어 (Soft language). "할 수 있습니다", "선택할 수 있습니다"와 같은 표현은 절대 사용하지 마세요. 독자가 실제로 그렇게 하는지 확인할 수 있는 사용자 지정은 "~할 수 있습니다"고 말하고, 반드시 수행해야 하는 단계는 "~하세요"고 말하세요. 2인칭 명령문은 명령처럼 들리지 않습니다. 그들은 가이드 역할을 합니다. 이 규칙은 페르소나 게이트가 통과된 후에 적용되므로 사용자는 이미 선택했습니다.
글머리 기호 안의 굵은 제목 (Bold headings inside bullets). 항상 전체 줄을 굵게 만드는 것은 가독성이 떨어집니다. 용어를 굵게 표시하거나 일반 텍스트를 사용하세요. 전체 항목에 굵은 제목이 필요한 경우 중첩 제목을 사용하세요.
역참조 (Back-references). 페이지가 다른 것의 일부인 경우를 제외하고 "위에서 언급한 바와 같이"는 사용하지 마세요. 그렇지 않으면 독자가 다른 것을 본 가정을 하지 마세요.
코드에 관한 추가 규칙:
- 코드블록에 독점적 메시지 (Exclusive messages in codeblocks). 업데이트나 오류를 코드 안에만 넣지 마세요. 본문 텍스트에도 넣으세요. 메시지를 건너뛴 독자는 코드블록을 보지 못할 수도 있습니다.
- 출력 스니펫 (Output snippets). 쉘 세션에 대한
$프롬프트를 생략하고 명령은 그대로 두세요.console.log,print등에서 잘린 출력을 보여주는 것은 괜찮지만, 전체 단말기 세션을 복사하여 붙여넣지 마세요. 출력이 산문에서 말하는 것을 설명하는 경우에만 포함하세요. - 오류 메시지 (Error messages). 독자가 직접 볼 수 있는 오류를 설명하거나 그들에게 유용한 오류를 설명하세요. 복사하여 붙여넣기 위해 전체 오류 메시지를 코드블록에 넣지 마세요. 대신 핵심 부분을 산문에서 말하세요.
- 생성된 출력 (Generated output). AI가 생성한 코드 스니펫이 독자가 실행할 수 있는지 확인하세요. 생성된 출력은 자리 표시자를 생성하는 경향이 있습니다. 자리 표시자를 사용해야 하는 경우 구체적이고 현실적으로 유지하세요.
라이브러리/프레임워크 중립성
문서가 특정 라이브러리나 프레임워크에 얽매이지 않아야 하는 경우 접근 방식이 있습니다. 예를 들어 스트리밍 문서는 Node.js만 다루어서는 안 됩니다.
먼저 사이트가 이미 어떻게 하는지 확인하세요. 프레임워크별 페이지를 가진 탭이 있는지, 아니면 한 페이지로 유지되고 설명이 중립적인지 확인하세요. 사이트 방식을 따르세요.
방식이 없으면 그냥 묻지 마세요. 지원되는 환경으로 연결되는 탭을 사용하세요. 예를 들어 세 가지 프레임워크를 지원하는 기능:
` ` ` <FrameworkTabs> <FrameworkTab label="Next.js"> Content for Next.js </FrameworkTab> <FrameworkTab label="Nuxt"> Content for Nuxt </FrameworkTab> <FrameworkTab label="Remix"> Content for Remix </FrameworkTab> </FrameworkTabs> `
아니면 간단한 마크다운 목록과 경로 링크를 사용하세요:
구성 요소 대체
사이트가 누락된 특정 구성 요소를 갖도록 마이그레이션 중이거나 업데이트를 계획 중인 경우에만 이 섹션을 사용하세요.
이 스킬은 구성 요소 이름과 더 간단한 HTML/마크다운 대체를 매핑합니다. 일치하는 항목을 찾을 수 없으면 페이지가 특정 구성 요소 없이 여전히 작업을 수행하는지 확인하세요.
| 구성 요소 | 대체 |
|---|---|
Steps / Step | 번호가 매겨진 마크다운 목록 (1., 2....) |
Tabs / Tab | 프레임워크별 제목이 있는 플랫 목록 또는 서로 다른 Tabs를 위한 별도의 페이지 |
Callout / Alert / Note / Warning | 굵은 레이블이 있는 인용구: > **⚠️ 경고:**, > **팁:** |
Cards | 인라인 하이퍼링크가 있는 작은 섹션 또는 페이지 목록 |
Accordion / Details | 요약을 첫 번째 단락으로 하는 평문 섹션 제목 |
CodeGroup / CodeTabs | 언어 주석이 있는 연속 코드블록 |
ParamTable / PropsTable / APITable | 마크다운 테이블 또는 굵은 용어 목록 (-**propName** + 설명) |
Tabs 내 CodeBlock | 플랫 마크다운 코드블록으로 실행 전에 언어 레이블을 먼저 넣기 |
문서가 멋져 보일 필요는 없습니다
아름다운 웹페이지가 아닙니다. 기능적인 설명서입니다.
- 아무도 문서의 웹사이트를 보기 위해 오지 않았습니다. 그들은 문제를 해결하기 위해 왔습니다.
- 모든 시각적 개선은 독자가 의도보다 페이지 디자인에 더 집중하게 하면 해가 됩니다.
- 완전한 정보가 부족한 예쁜 페이지보다 단순하고 완전한 정보가 있는 페이지가 낫습니다.
상호작용 학습, 비디오, 스크린샷, 순수 시각적 요소가 가끔 유용할 수 있지만 문서를 계획할 때는 기본값으로 가정하지 마세요. 대부분의 페이지는 상호작용이 필요하지 않습니다.