syscross_dev — 문서 작성 스타일 가이드
Obsidian 기반 노트를 Quartz로 빌드해 syscross.dev에 배포하는 저장소. sh publish.sh로 빌드+배포.
글쓰기 스타일 (과학/수학 등 개념 문서 기준)
- 반직관 포인트를 먼저 찾아 지적한다. “~라고 알고 있지만 사실은 ~다” 구조의 자문자답을 자주 쓴다. 독자가 당연하다고 넘길 지점을 짚어서 흥미를 끈 다음 설명으로 들어간다.
- 비유를 적극 사용한다. 추상 개념(전위차, 전자구름 등)은 일상 비유(물탱크 높이, 바다-수도관, 확률구름)로 먼저 감을 잡힌 뒤 수식/전문용어로 넘어간다.
- 역사와 어원을 곁들인다. 용어가 왜 그렇게 정해졌는지(앙페르→암페어, 벤자민 프랭클린의 부호 오류, 톰슨의 전자 발견) 서술해 단순 암기가 아니라 맥락으로 기억하게 한다.
- 용어는 처음 등장할 때 한글(영어) 병기. 예: 전위차(potential difference), 전류(electric current).
- 문단은 짧게. 한두 문장이 한 문단인 경우가 많다. 산문 설명과 불릿 리스트를 섞어 가독성을 높인다.
- 공식은 유도 과정을 보여준다. 결과만 던지지 않고 “왜 이 식이 나오는지”를 기하학적/물리적으로 설명한다(예: 전기장이 거리의 제곱에 반비례하는 이유를 구 표면적 4πr²로 설명).
- 헷갈리기 쉬운 부분을 명시적으로 교정한다. 예: “궤도가 아니라 구름이다”, “밑변/높이가 아니라 adjacent/opposite다” 같이 흔한 오개념을 짚고 바로잡는다.
- 문서 하단에 학습 순서를 명시한다. “사전 필요 개념”(prerequisite)과 “관련 문서”(다음에 읽을 것) 섹션을 둬서 문서 간 체인을 만든다. 상위 인덱스 문서(예: 전자기학.md)에는 “읽는 순서”를 따로 정리한다.
- 핵심 요약은 콜아웃으로.
> [!Tip]같은 Obsidian 콜아웃으로 핵심만 다시 짚어준다. - 법령/규정형 문서는 스타일을 달리한다. KEC처럼 암기가 핵심인 영역은 비유보다 조문·수치표 중심으로 정리한다(아직 미착수).
디렉토리 원칙
- 분류 체계:
_ko-kr/과학,_ko-kr/수학,_ko-kr/자격증/전기기사등 영역별 상위 폴더 아래 개념 단위 문서. - 각 영역 상위 문서(예:
과학.md,수학.md)는 인덱스 역할만 하고, 하위 문서로 링크한다. - 일본어 한자 테이블 등 특수 포맷은 해당 분야 고유 컨벤션을 따른다(예:
_ja-jp/漢字/하위 교육한자·상용한자 표 컬럼 규칙).
빌드/배포
sh publish.sh
내부적으로 npx quartz sync --no-pull을 실행해 ../.target에 빌드하고 origin/main에 반영한다.