IbrahimSobh/content-explainer-slide

콘텐츠 설명 슬라이드

translate-content-explainer-slide 에이전트가 기술 작업의 스토리를 알려주는 단일 이미지를 구축합니다. 발견된 것, 잘못된 것, 수행된 작업과 각 단계가 작동하는 이유, 모든 숫자의 출처, 달성한 성과와 교훈을 포함합니다.

기준은 주니어 엔지니어에게 100% 명확하고 직관적이어야 하며, 100% 상세할 필요는 없습니다. 이 기준은 실제 검토 과정에서 나왔습니다. 용어가 정의되지 않았거나, 숫자의 출처가 보이지 않거나, 단계의 이유가 각주에 숨겨져 있거나, 카드에 빈 영역이 있을 때마다 독자는 "이게 뭐죠?", "30은 어디서 나왔나요?", "왜 그게 작동하나요?"라고 질문했고, 슬라이드는 또 다른 수정이 필요했습니다. 아래의 모든 내용은 독자가 질문하기 전에 슬라이드에서 이러한 질문에 답하기 위해 존재합니다.

완성된 슬라이드 계획의 예시(신경망 "뉴런 수술" 실험)는 references/worked-example.md에 있습니다. 첫 번째 슬라이드를 계획하기 전에 한 번 읽어보세요. 각 카드가 규칙이 적용되었을 때 어떻게 보이는지 보여줍니다.

0단계 — 출력 형식 물어보기, 그런 다음 사실 시트 구축

형식 물어보기 (그리기 전, 한 번만)

사용자가 이미 말하지 않은 경우, 원하는 출력 형식을 물어보세요.

• Python matplotlib을 통한 PNG — 입력에 데이터, 모델, 로그 또는 결과 파일이 있을 때 가장 좋습니다. 스크립트가 슬라이드의 모든 숫자를 해당 파일에서 직접 계산할 수 있기 때문입니다(수동 입력 숫자 없음). JPG 사본도 내보냅니다.
• HTML/SVG 페이지를 PNG로 렌더링 — 입력이 텍스트 전용(논문, 문서, 노트)이거나, 타이포그래피 및 레이아웃 정교함이 숫자 계산보다 더 중요할 때 가장 좋습니다. 헤드리스 Chrome/Edge로 PNG로 렌더링됩니다.
• 둘 다 — 동일한 슬라이드 계획, 두 가지 렌더링.

이유와 함께 권장 사항을 명시하세요(데이터 입력 → matplotlib; 텍스트 입력 → HTML). 사용자에게 물어볼 수 없는 경우(자동 실행), 해당 규칙에 따라 선택하고 선택한 형식과 이유를 말하세요.

사실 시트 구축

디자인하기 전에 슬라이드에서 사용할 수 있는 모든 사실을 나열하세요. 각 사실에 대해 다음을 기록합니다.

사실	값	측정 대상(어떤 데이터 / 어떤 섹션)	출처(파일 + 스크립트, 또는 논문 페이지/표)

그런 다음:

• 사실들을 서로 교차 확인하고 초안 텍스트(게시물, 초록, README)와도 확인하세요. 지금 불일치를 모두 해결하세요. — 슬라이드에서 38이라고 말하는데 게시물에서 36이라고 말하면 신뢰가 무너집니다. 이러한 불일치는 일반적으로 두 곳에서 "동일한" 숫자를 다르게 계산(다른 샘플 크기, 다른 임계값)하기 때문에 발생합니다.
• 데이터 분할을 기록하세요. 방법을 구축하는 데 사용된 것과 테스트하기 위해 보류된 것입니다. 슬라이드에 이를 명시해야 합니다. 왜냐하면 "결과가 전혀 보지 못한 데이터에서도 유효한가?"는 기술 독자가 가장 먼저 묻는 질문이기 때문입니다.
• 두 가지 모드:
  • 데이터 모드(결과, 모델, CSV, 로그 존재): 그리기 스크립트가 이를 로드하고 렌더링 시 모든 숫자를 계산합니다.
  • 소스 모드(텍스트 전용): 모든 숫자가 소스에서 복사되며 사실 시트는 출처(페이지, 표, 그림)를 인용합니다. 소스에 명시된 것 이상으로 숫자를 만들거나 반올림하지 마십시오.

이후 편집 시 일관성을 유지할 수 있도록 사실 시트를 슬라이드 옆에 저장합니다(<name>_facts.md).

1단계 — 스토리 찾기 (3~6개의 번호가 매겨진 카드)

각 질문에 한 문장씩 답변하세요. 각 답변은 하나의 카드가 됩니다.

1. 발견 / 맥락 — 무엇이 발견되었거나, 설정이 무엇인지.
2. 문제 — 무엇이 잘못되었거나 누락되었는지, 측정된 상태. 여러 문제가 있는 경우 이름을 지정하십시오(문제 A, 문제 B). 대상이 되는 것 과 의도적으로 대상이 되지 않는 것, 그 이유를 명시하십시오. — 차트에서 약한 항목을 보고 설명이 없으면 독자는 실수라고 가정합니다.
3. 방법 — 하나의 사례에 대한 레시피를 단계별로.
4. 하나의 사례에서 모든 사례로 — 레시피가 어떻게 모든 곳에 적용되었는지, 개수를 결정한 규칙 및 개수. 각 수정 사항을 해결하는 문제와 연결하십시오("수정 A → 문제 A").
5. 결과 + 교훈 — 무엇이 바뀌었는지, 확신의 정도, 가르쳐주는 것.

동일한 내용을 말하는 카드는 병합하십시오(중복 카드는 검토 시 매번 제거되었습니다). 입력이 작은 경우 카드 3과 4가 병합되거나 슬라이드가 3개의 카드(문제 → 방법 → 결과)가 될 수 있습니다. 최대 6개를 초과하지 마십시오. — 그 이상은 슬라이드가 아닌 덱입니다.

2단계 — 헤드라인

상단에 한두 줄: 놀라운 사실 + 취한 조치, 예: "M개 중 N개 부품이 아무 일도 하지 않고 있었습니다. 그래서 그들에게 일을 맡겼습니다." 헤드라인은 사람들이 스크롤을 멈추게 만드는 요소입니다. 카드는 신뢰를 주는 요소입니다. 헤드라인 숫자는 사실 시트 / 스크립트 변수에서 가져오며, 수동으로 입력하지 않습니다.

3단계 — 카드 스켈레톤 (모든 카드 동일)

• 번호 + 강조 색상. 각 카드는 큰 번호(1–5)와 고유한 강조 색상을 가지며, 테두리와 하이라이트에 사용됩니다. 번호는 읽기 순서를 제공합니다. 색상을 사용하면 이후 카드에서 이전 카드를 가리킬 수 있습니다("카드 4의 11개 감지기").
• 제목 = 카드가 답하는 질문.
• 굵은 요약 문장 하나 = 답변.
• 하나의 주요 그림. 방법 카드는 단계 셀 그리드를 사용할 수 있습니다. 결과 카드는 차트와 설명 패널을 사용할 수 있습니다.
• 데이터 레이블 — 이 카드가 사용하는 데이터와 해당 데이터를 사용하는 이유("60,000개 훈련 이미지 중 18,000개(30%) — 최종 확인의 공정성을 위해 나머지는 보지 않은 상태로 유지됨").
• 짧은 각주 — 주의 사항만. 추론은 절대 각주에 넣지 않습니다(4단계 참조).

4단계 — 방법 카드: WHAT / 그림 / WHY 셀

방법을 3~5개의 번호가 매겨진 셀로 분할합니다(4개일 때 2×2 그리드). 모든 셀은 상단에서 하단으로 동일한 세 개의 밴드를 갖습니다.

1. 캡션 (WHAT) — 무엇과 무엇을 비교하는지를 말하는 구체적인 작업: "일치됨"이 아니라 "2단계의 패턴과 새로운 이미지(전혀 본 적 없는)를 비교".
2. 그림 — 데이터 또는 출처의 실제 예로 구축: 실제 입력, 실제 중간 결과, 실제 점수. 실제 예는 추상적인 단계를 믿을 수 있게 만듭니다. 일반 아이콘은 아무것도 가르치지 않습니다.
3. WHY 상자 — 전체 너비, 고정 높이, 시각적으로 스타일링됨(색조 배경, "WHY?" 레이블). 단계가 작동하는 이유를 설명합니다.

WHY는 그림 안에 눈에 띄게 있어야 합니다. 검토 시 각주에 배치된 추론은 매번 놓쳤고 독자는 반복해서 질문해야 했습니다. 셀 내부에서 독자가 물을 질문에 답하십시오.

• 왜 명백한 선택 대신 이 선택인가? (예: 올바른 클래스의 평균을 빼는 이유)
• 이것은 무엇에 영향을 미치지 않으며, 그 이유는? (예: "'3'만 낮출 수 있습니다. 다른 클래스가 이미 이기고 있으면 아무것도 변하지 않습니다.")

메커니즘을 이전 → 이후로 표시하십시오. 점수/상태의 작은 패널, 화살표, 이후 패널, 승자에 ✓/✗, 화살표에 짧은 설명("2번째로 높은 것이 승리"). 패널 제목이 아래에 맞지 않으면 옆에 배치하십시오.

그림이 실제를 단순화하는 경우(픽셀을 표시하지만 실제 계산은 내부 특성을 사용하는 경우), 각주에 명시하십시오. — 단순화에 대한 정직함은 한 줄의 비용으로 "그게 어떻게 작동하는 게 아니야"라는 댓글을 방지합니다.

작업 예제를 "예시:" 로 표시하고 일반 규칙("30개 감지기 모두 동일한 레시피")을 명시하십시오. 그렇지 않으면 독자는 방법이 해당 사례만 다룬다고 생각합니다.

5단계 — 모든 숫자 추적 가능하게 만들기

• 각 숫자의 출처를 보이는 체인으로 표시하십시오: "21개 예시 → 3개 스타일 → 3개 감지기", "11 + 19 = 30/36 (6개 예비)". 합계가 명확하게 더해져야 하며, 잔여분에는 이유가 필요합니다.
• 개수를 생성한 선택 규칙 및 임계값을 명시하십시오("스타일에는 ≥2개 예시 필요", "학습하기에는 너무 적으므로 <3개 예시인 실수는 건너뜀").
• 데이터가 다른 출처(레이블링 vs. 마이닝, 측정 vs. 추정)에서 온 경우, 범례와 함께 시각적으로 표시하십시오(어두운 막대 vs. 밝은 막대).
• 처음 나타날 때 모든 표기법을 설명하십시오("×N = 해당 실수에 대한 N개 스타일 감지기").
• 데이터 모드에서 스크립트는 모든 숫자를 계산합니다. 텍스트 문자열은 변수(f-strings / 템플릿 값)를 사용합니다. 수동으로 입력한 숫자는 데이터와 동기화되지 않아 실제로 잘못된 슬라이드가 발생했습니다.

6단계 — 정직한 결과, 모든 변경 사항 설명

• 방법을 구축하는 데 사용되지 않은 데이터에 대한 이전 → 이후; 가능한 경우 두 번째 사용되지 않은 데이터 세트에서 확인합니다.
• 이익 과 손실을 모두 제공하십시오("34개 수정, 9개 손상"). 이익만 있는 결과는 선별된 것으로 읽힙니다.
• 통계를 평이한 언어로("운으로 약 600만 분의 1") 제공하고, 기술적 형식은 작게 또는 각주에 넣습니다.
• 항목별 변경 차트(이후 − 이전, 양수 / 음수 / 0으로 색상 지정) 와 "각각 변경된 이유" 패널: 이익이 발생한 이유, 손실이 발생한 이유, 추가 부작용. 손실을 이유 없이 나열하면 최악의 해석을 불러옵니다.

7단계 — 평이하고 일관된 단어

• 모든 용어를 처음 사용 시 몇 개의 평이한 단어로 정의하거나, 평이한 단어로 대체하십시오.
• 슬라이드 전체에서 개념당 하나의 단어("예측됨"을 항상 사용, 가끔 "응답됨"이라고 하지 않음).
• 슬라이드에 정의되지 않은 내부 별명("세트 A", "트위스트", "운 좋은 부작용", "×3")은 사용하지 마십시오.
• 모든 주장은 차트와 일치해야 합니다. 차트에 텍스트가 다루지 않는 이상한 부분이 있으면 다루십시오.

8단계 — 범례 및 색상

• 모든 색상, 음영, 화살표 및 기호가 나타나는 곳에 설명됩니다. 발산 이미지는 "빨간색 = X에만, 파란색 = Y에만"을 얻습니다.
• 슬라이드 전체에 걸쳐 하나의 색상 의미: 예: 빨간색 = 문제/제거됨, 녹색 = 수정됨/좋음, 회색 = 중립. 카드 강조 색상은 이러한 의미적 색상과 분리됩니다.
• 그룹화된 항목(하나의 실수 스타일, 하나의 단계 변형)은 그룹이 서로 흐려지지 않도록 눈에 보이는 상자 안에 배치합니다.

9단계 — 결론 및 교훈 배너

• 결론 배너(녹색 색조): 보여진 것, 크기 및 한계 포함("작지만 실제적인 이득, 새로운 데이터에서 유지됨").
• 교훈 배너(슬라이드 하단): 독자가 다른 문제에 적용할 수 있는 것.

10단계 — 레이아웃

• 16:9(예: 150dpi에서 16×9인치, 또는 1600×900px 캔버스). 카드는 스토리 순서대로 왼쪽→오른쪽으로 읽습니다.
• 카드 크기는 내용에 맞게 조정하십시오. — 방법 카드는 일반적으로 가장 넓습니다. 큰 빈 영역이 없어야 합니다. 카드에 여유 공간이 있으면 차트를 넓히거나 텍스트 패널을 공간으로 이동하십시오.
• 겹치는 텍스트가 없어야 합니다. 레이블은 상자 안에 유지됩니다. 휴대폰 가독성(16×9인치에서 약 7.5pt가 최소) 이하로 글꼴을 줄이는 대신 긴 줄을 줄 바꿈하십시오.
• 레이아웃 코드는 references/matplotlib-recipes.md(PNG) 또는 references/html-recipes.md(HTML)를 참조하십시오. scripts/slide_kit.py는 matplotlib 도우미(카드, 단계 셀, WHY 상자, 이전/이후 점수 패널, 배너, PNG+JPG 내보내기)를 제공합니다. 다시 작성하지 말고 가져오십시오.

11단계 — 렌더링, 검사, 수정, 반복

1. 이미지를 렌더링합니다.
2. 실제 이미지를 확인하십시오. — PNG를 열고 각 카드를 확대합니다(필요하면 자르기). "맞아야 하는" 코드가 맞지 않는 경우가 많습니다. 겹침 및 잘린 텍스트는 렌더링에서만 볼 수 있습니다.
3. references/checklist.md를 카드별로 검토하십시오. 마치 처음 보는 주니어 엔지니어처럼.
4. 수정, 재렌더링, 재확인. 체크리스트를 통과하지 못한 슬라이드를 사용자에게 보여주지 마십시오.

12단계 — 변형 및 최종 확인

• 기술 독자를 위한 상세 버전(모든 숫자). 폭넓은 청중을 위한 간단 버전을 제공하십시오. 동일한 스토리, 더 적은 정확한 숫자.
• LinkedIn/X용 JPG 사본(투명도 없음)을 내보냅니다.
• 게시하기 전에 슬라이드 또는 관련 게시물에 나타나는 모든 외부 주장 또는 인용을 확인하십시오. 확인할 수 없는 것은 표시하십시오.
• 전달: PNG(+ JPG), 그리기 스크립트 또는 HTML 소스, 사실 시트. linkedin-arabic-science-post, tweet-post 또는 figure-animator가 완성된 슬라이드에서 게시물 또는 애니메이션 버전을 생성할 수 있다고 언급하십시오.