강의 사이트에 수식보다 이유를 먼저 설명하는 장 쓰기

## 강의 페이지와 번역 페이지를 둘 곳 정하기 이 프로젝트는 저장소 안의 소스 파일로부터 만들어지는 정적 문서 사이트다. 기여자가 무엇이 어디에 있는지 짐작할 수 있도록 트리를 예측 가능하게 유지한다: - `docs/` — 게시되는 페이지가 되는 강의 콘텐츠. - 콘텐츠 트리 안의 사이트 설정 디렉터리 — 정적 사이트 생성기를 위한 설정과 테마 재정의. - `docs/public/` — 최종 사이트로 그대로 복사되는 정적 자산. - 콘텐츠 트리 안에 언어별로 하나씩 두는 디렉터리 — 주 언어의 구조를 그대로 반영하는 번역 트리. 번역 트리에서는 뼈대만 있는 스텁 페이지를 자리 표시자로 두어도 된다. - `code/` — 본문과 장별로 대응되는, 실행 가능한 실험 코드. - `scripts/` — 사이트맵 생성, 검증, 자산 최적화 같은 저장소 유지관리 스크립트. - CI 워크플로 디렉터리 — 사이트를 빌드하고 배포하는 파이프라인. 새 자료는 콘텐츠 디렉터리 아래에 넣는다. 내비게이션과 사이드바 항목은 사이트 설정 파일에 선언하며, 파일이 놓인 위치만으로 추론되게 하지 않는다. ## 프로젝트 명령으로 사이트를 내 컴퓨터에서 띄워 확인하기 모두가 같은 파이프라인을 실행하도록, 하위 도구를 직접 호출하지 말고 프로젝트가 제공하는 스크립트 진입점을 통해 작업한다. 이런 형태의 문서 사이트는 소수의 고정된 진입점만 노출한다: - `npm install` — 의존성 설치. - `npm run dev` — 자산 최적화를 포함한 개발 서버. - `npm run dev:fast` — 자산 최적화를 건너뛰어 훨씬 빠르게 시작하는 개발 서버. - `npm run build` — 게시 가능한 결과물 생성. - `npm run preview` — 빌드된 결과물을 게시될 모습 그대로 제공. - `npm run verify` — 저장소 전체의 일관성 검사. - `npm run assets:optimize` — 이미지 압축 및 변환. 본문을 편집하는 동안에는 빠른 개발 변형을 사용한다. 그때 보고 있는 것에 이미지 최적화는 아무런 영향을 주지 않기 때문이다. 결과물을 게시될 모습 그대로 확인해야 할 때는 `build` 다음에 `preview`를 사용한다. `verify`는 다음 부분에서 설명하는 관문이고, `assets:optimize`는 이미지를 추가한 뒤에 실행해서 용량이 큰 원본이 게시된 사이트에 절대 들어가지 않게 한다. ## 페이지를 더하면 모든 언어의 메뉴를 고치고 공개 전에 점검하기 - 모든 변경을 지금 맡은 작업의 범위 안에 묶어 둔다. 지나가는 김에 관련 없는 문서나 설정을 고쳐 쓰지 않는다. - 이미 존재하는 자료를 재구성하기보다, 콘텐츠 디렉터리 아래에 새 강의 자료를 추가하는 쪽을 택한다. - 새 페이지를 추가할 때는 내비게이션과 사이드바 설정에 등록한다. - 페이지를 추가하거나 옮기거나 이름을 바꿀 때는, 주 언어 트리만이 아니라 그것을 반영하는 모든 언어 트리의 사이드바를 갱신한다. 뒤처진 번역 트리는 죽은 항목이나 없는 페이지를 만들어 낸다. - 설정, 테마, 빌드 스크립트를 건드렸다면 푸시하기 전에 반드시 검증 명령을 실행한다. 푸시는 곧 사이트 게시이므로, 검증되지 않은 빌드는 공개된 상태에서 사이트를 망가뜨린다. ## 수식이 든 그림을 LaTeX로 쓰고 SVG로 바꿔 쓰기 실제 수식 조판이 들어간 학술 양식의 도해는 손으로 그리지 않고 소스로 작성한다: 1. 도해를 벡터 도해 언어로 된 독립 문서로 작성한다 — 예를 들어 TikZ 계열 패키지를 사용하는 LaTeX standalone 문서로 작성한다. 새로운 양식을 만들어 내지 말고, 저장소에 이미 있는 도해의 양식을 그대로 따른다. 2. 사용하는 폰트를 지원하는 LaTeX 엔진으로 소스를 컴파일한 다음, 생성된 PDF를 PDF-to-SVG 변환기로 SVG로 변환한다. 두 단계 모두 명령줄 도구이므로, 어떤 도해든 언제든지 소스에서 다시 빌드할 수 있다. 3. 소스 파일과 생성된 SVG를 둘 다 같은 `images/` 디렉터리, 즉 그것을 사용하는 장 옆에 두어 도해의 재현 가능성을 유지한다. 4. 생성된 SVG는 마크다운 페이지에서 상대 경로로 참조한다. 모든 도해에 하나의 시각 양식을 일관되게 적용한다: 아주 옅은 채움과 짙은 회색 선을 가진 모서리가 둥근 상자, 단일한 화살촉 양식, 본문과 어울리는 본문 폰트, 그리고 기호를 위한 인라인 수식 구분자. ## 수다 떠는 말투가 아닌 차분한 강의 말투로 쓰기 - 각 장을 간결한 참조용 메모가 아니라 튜토리얼이자 강의 자료로 쓴다. - 안내하는 강의의 목소리를 유지한다: 대화하듯, 참을성 있게, 문제에서 출발하는 방식으로. 독자에게 다음 걸음을 건네주는 표현 — "먼저 직관에서 출발해 보자", "다른 각도에서 보자", "이 단계가 뜻하는 바는…", "진짜 문제는…" — 은 환영하되, 어조는 진지하고 정확하게 유지한다. - 수다스럽거나 비서 같거나 가벼운 인터넷 말투로 빠지지 않는다. 목표로 하는 문체는 잘 다듬어진 교과서의 한 장이다. - 소리 내어 읽거나 혼자 따라갈 수 있도록 문단의 속도를 조절한다. 읽는 속도로 따라갈 수 없는 문단이라면 나눈다. ## 이유의 흐름을 모두 설명하고 알맹이 없는 머리말은 쓰지 않기 깊이와 절약은 함께 간다: 추론의 사슬 전체를 설명하되, 그 사슬 밖의 것에는 한 단어도 쓰지 않는다. - 점진적으로 설명한다 — 직관이 먼저, 그다음 형식적 정의, 그다음 코드나 실습. - 배경과, 그 단계가 왜 필요한지의 이유를 제시한다. 한 장을 결과만 나열한 목록으로 압축하지 않는다. - 안내용 군더더기를 잘라낸다. 설명을 하는 대신 설명을 하겠다고 예고하는 문장("예를 들면 더 직관적으로 이해될 것이다")은 삭제하고, 예시나 수식을 곧바로 제시한다. - 같은 것을 한 번만 말한다. 같은 요점을 다른 말로 되풀이하지 않는다. - 모호한 한정어를 정확한 인과 진술로 바꾼다. 비유적인 대체 표현("이것은 대략 …와 같다")과 얼버무리는 접속 표현은 초고에만 있어야 한다. - 메커니즘을 귀에 걸리는 문구로 압축하는 표어 같은 요약 표현을 피한다. 대신 구체적인 메커니즘을 서술한다. - 나란한 실수를 기계처럼 나열하는 것을 피한다("질의가 너무 넓었고, 가격 비교가 없었고, 재고 수준이 틀렸고, 매개변수가 틀렸다"). 과정을 서술하고, 초반의 잘못된 상태 하나가 이후의 행동으로 어떻게 전파되는지를 보여준다. - "A가 아니라 B다" 식의 대조 패턴을 피한다. 그것은 에두르는 인상을 준다. 긍정 주장을 먼저 진술하고, 왜 그것이 성립하는지 설명한다. ## 새 단계마다 왜 필요한지 먼저 말하는 순서로 생각 배열하기 - 인과의 선을 따른다. 같은 요점을 요약하고, 다시 말하고, 그다음 대조하면서 맴돌지 않는다. 실제로 생각이 바뀌는 순서대로 쓴다: 새로운 능력이나 설정이 등장하고, 그것이 학습 대상이나 문제 대상을 바꾸며, 그로 인해 새로운 정식화가 가능해지거나 불가피해진다. - 새로운 개념을 열 때는 "이제 X가 존재하므로, 시스템은 Y를 하고, 따라서 Z가 가능해진다(혹은 필요해진다)"라는 형태를 택한다. - 독자가 이미 아는 것과 연결하며 절을 열고, 그다음 이 절이 푸는 새로운 문제를 이름 붙여 제시한다. - 바로 다음 문장에 그 참조가 필요한 경우가 아니라면, 앞선 장을 다시 불러오지 않는다. - 모든 개념적 단계에 전환을 준다. 정의에서 수식, 용어, 알고리즘, 결론으로 곧장 건너뛰지 않는다. 다음 생각을 도입하기 전에 그것이 왜 필요한지를 먼저 말한다. - 정의만 나열하는 백과사전식 페이지를 쓰지 않는다. 정의는 그 동기 뒤에 오고, 그 뒤에는 해석이 따라온다. - 문단이 질문에서 답으로 흐르게 한다. 잘 짜인 절은 대개 다음 리듬을 따른다: 익숙한 예시 → 긴장 또는 혼란 → 형식적 도구 → 풀이 예제 → 핵심 정리. ## 수식 전에 익숙한 예를 들고 기호를 하나씩 설명하기 - 수식이나 알고리즘을 도입하기 전에, 그것이 푸는 문제를 먼저 진술한다. 표기법은 그다음에 보여준다. - 수식을 그 의미 옆에 둔다: 중요한 기호를 모두 설명하고, 그다음 수식 전체를 평이한 말로 다시 진술한다. - 추상화보다 구체적인 장면을 먼저 꺼낸다. 막대 균형 잡기 제어 과제, 다중 슬롯머신(multi-armed bandit), 텍스트 생성, 게임 과제, 일상의 선택 같은 작고 익숙한 설정이, 개념에 이름이 붙기 전에 그 개념이 필요하다고 느끼게 만들어야 한다. - 결과를 단언하는 대신 작은 유도를 포함하고, 본문 전체를 학습자를 향한 글로 유지한다. - 정착된 대응어가 있는 한, 빌려온 영어 단어를 번역하지 않고 남겨두지 말고 본문의 주 언어로 기술 용어를 쓴다. 영어 용어는 표준 약어일 때나 장 제목이 그것을 요구할 때만 남기고, 처음 나올 때 설명한다. - 하나의 개념에는 강의 전체에 걸쳐 하나의 고정된 단어를 쓴다. 장마다 흔들리는 동의어는 학습자에게 두 번째 개념으로 읽힌다. ## 짧은 소제목 단위로 나누고 커밋 앞에 feat: 같은 표시 붙이기 - 나뉘지 않은 긴 글 덩어리 대신, 명시적인 제목을 가진 짧은 절을 사용한다. - 굵은 글씨는 개념의 전환점을 표시하기 위해 아껴 쓰고, 장식으로는 절대 쓰지 않는다. - 콘텐츠 디렉터리 아래의 경로에는 kebab-case를 사용한다. - 안에 `index.md`를 두는 디렉터리 기반 경로를 택해, 한 주제가 URL을 바꾸지 않고도 여러 페이지로 자라날 수 있게 한다. - 모든 변경에 Conventional Commits를 사용한다: `feat:`, `fix:`, `docs:`, `chore:` 등.