문서 스타일 가이드 | EmDash CMS Everything

이 가이드는 EmDash 문서가 어떻게 작성되는지 정의합니다. 기여물은 이에 맞게 편집됩니다. 외울 필요는 없습니다 — 리뷰어와 편집자가 도와줍니다 — 하지만 따르면 기여물의 병합이 빨라집니다.

문서는 누군가가 무언가를 하고 프로젝트로 돌아가는 것을 돕기 위해 존재합니다. 피곤하고, 서두르고, 제2언어로 읽거나, 스택에 익숙하지 않은 독자를 위해 작성하세요. 무엇보다 그 독자를 위해 봉사하세요.

가독성

다음을 선호하세요:

짧은 문장과 짧은 단락.
전문 용어보다 평이한 어휘.
약어와 두문자어는 처음에 풀어쓰기.
긴 구절을 나누기 위한 제목과 목록.
능동태.

EmDash로 어떻게 구축하는지를 문서화하고, EmDash가 어떻게 구축되었는지는 문서화하지 마세요. 구현 세부사항은 독자가 내려야 하는 결정을 변경하는 경우에만 문서에 포함합니다 (기본값이 아닌 값을 선택할 때, 프로젝트에 영향을 미치는 주의사항). 사용 예시를 대체하지 않습니다.

EmDash 이외의 주제 — TypeScript, AT Protocol, 웹 폰트, SQL — 에 대해서는 설명하는 대신 신뢰할 수 있는 출처에 링크하세요. EmDash에서 기능을 사용하기 위해 알아야 할 것을 문서화하세요.

무엇을 강조할 것인가

페이지의 강조는 독자가 작업을 수행하는 데 필요한 것에 의해 결정되어야 하며, EmDash를 구축한 사람들에게 흥미롭거나 최근이었던 것에 의해서는 안 됩니다. 적극적으로 저항해야 할 세 가지 습관:

작성 최신성 가중치. 결정이 새롭거나 작성자의 마음에 신선하다는 것은 그것을 특집으로 내세울 이유가 아닙니다. 가장 많이 변경된 것이 독자에게 가장 중요한 것인 경우는 드뭅니다. 섹션, 목록 항목, 제목을 독자가 얼마나 자주 필요로 하는지에 따라 정렬하고, 추가된 시기에 따라 정렬하지 마세요. 방금 변경되었기 때문에 무언가를 문서화하고 있다면, 아마 문서가 아니라 변경 로그 항목을 쓰고 있는 것입니다.
독자 관련성보다 구축자 관련성. 내리기에 중요했던 내부 아키텍처와 설계 결정은 사용하기에는 보통 보이지 않고 무관합니다. 독자가 얻는 기능을 명시하고, 그 뒤의 메커니즘은 명시하지 마세요. 컬렉션을 정의하는 독자는 파서의 언어를 알 필요가 없는 것처럼 스키마가 어디에 저장되는지 알 필요가 없습니다. 메커니즘이 EmDash에서 작업하는 사람을 진정으로 돕는다면, 사용자 대면 페이지가 아닌 내부 문서에 속합니다.
허수아비 자기 정의. EmDash를 다른 도구의 캐리커처와의 대비로 정의하지 마세요 (“대부분의 CMS와 달리…”, “전통적인 CMS는 당신을 강제합니다…”, “많은 CMS에서 코드로 X를 선언합니다”). EmDash가 무엇을 하는지 직접 설명하고 스스로 서게 하세요. 비교는 비교가 독자 자신의 질문인 경우에만 허용됩니다: 평가 페이지와 ”…에서 왔다면” 오리엔테이션 페이지에서. 거기서도 구체적이고 공정해야 합니다 — 구체적인 동작과 트레이드오프이지, 독자가 싫어하도록 초대되는 허수아비가 아닙니다.
부정에 의한 정의. 기능을 하지 않아도 되는 작업으로 프레이밍하는 것 — “작성할 마이그레이션 없음”, “리빌드 없음”, “코드를 건드리지 않고”, “별도 서비스 없음” — 은 위장된 허수아비입니다: 당신이 그들을 위해 발명한 대안을 짊어진 독자에게만 통합니다. 독자가 _무엇을 하는지_와 _무엇이 일어나는지_를 명시하세요. “관리 패널에서 필드를 추가하세요; 즉시 적용됩니다” — “마이그레이션 없이, 리빌드 없이, 코드 없이 필드를 추가하세요”가 아닙니다. 예외는 긍정적으로 표현된 구체적이고 독자에게 관련된 동작입니다: “콘텐츠는 런타임에 제공되므로 편집이 즉시 나타납니다”는 EmDash에 대한 사실입니다. “리빌드가 필요 없음”은 다른 사람의 부재한 고통으로 표현된 같은 사실입니다 — 전자를 선호하세요.

모든 문장의 테스트: 작업을 마치려는 독자가 삭제되면 더 나빠질까요? 그렇지 않다면 삭제하세요. EmDash를 다른 것과 비교하는 독자에게만 의미가 있다면, 잘못된 위치에 있거나 잘라내야 합니다.

상록수, 변경 로그가 아님

사용자 대면 페이지는 이전 버전이 머릿속에 없는 독자를 위해 EmDash가 지금 어떻게 작동하는지 설명합니다. “지금”, “더 이상 아닌”, “이전에는”, “오래된 것 대신”, “이것이 변경되었습니다”는 없습니다. 버전 간 차이는 업그레이드 가이드에만 존재합니다. 개념이 최근에 도입되었다는 것은 최근이라고 언급할 이유가 되지 않습니다.

목소리와 톤

중립적이고 사실적인 문장을 쓰세요. 사실을 직접 명시하세요.

✅ 플러그인은 격리된 런타임에서 실행되며 선언한 API에만 접근할 수 있습니다.

❌ 플러그인은 나쁜 일이 절대 일어나지 않는 아늑한 작은 샌드박스에 살고 있어요!

우리, 저희, 우리의 또는 _합시다_를 사용하지 마세요. 당신은 독자와 함께 앉아 있지 않습니다. 독자에게 직접 말하거나 시스템을 설명하도록 다시 표현하세요.
_나_는 절대 사용하지 마세요. 문서는 저자에 대한 것이 아닙니다.
필요할 때 독자를 _당신_으로 지칭하세요, 특히 무언가가 잘못될 수 있는 단계를 표시할 때.
내러티브나 이야기를 하지 마세요. “이제 X를 설정했으니 Y로 넘어갑시다”는 없습니다. 섹션은 목표로 시작하고, 그다음 단계입니다.
기발함, 마스코트, 문화적 참조를 피하세요. 읽는 노력을 추가하고 번역되지 않습니다.
느낌표는 드뭅니다. 진정으로 격려적이거나 놀라운 것에만 사용하세요. 확실하지 않으면 마침표를 사용하세요.

제목

페이지 제목은 <h1>입니다 (프론트매터 title에서). 섹션은 <h2>부터 시작합니다.
제목을 짧게 유지하세요. <h2>와 <h3>는 “이 페이지에서” 사이드바에 나타납니다. 미리 보고 줄바꿈되는 것을 줄이세요.
콜론을 포함한 후행 구두점 없음.
제목에서 코드를 본문과 동일하게 <code>로 포맷하세요.

순서가 중요하지 않을 때, 옵션이나 속성의 집합과 같은 경우에 글머리 기호 목록을 사용하세요.
순서대로 따라야 하는 단계에는 번호 매긴 목록을 사용하세요. 절차에는 Starlight의 <Steps> 컴포넌트를 사용하세요.
목록 항목이 여러 단락으로 커지거나 여러 코드 용어를 포함하면 대신 <h3> 섹션으로 전환하세요.

예시

“예를 들어”는 단일 예시나 가정을 도입합니다.
괄호 안의 “예:“는 비포괄적 목록을 도입합니다 (예: GitHub, GitLab).
모든 옵션을 다루는 목록은 예시 목록이 아닙니다 — “예:” 없이 괄호를 사용하세요 (필수 속성 (src, alt)).

스크린샷

스크린샷은 공간적 관계, 인터페이스 상태 또는 컨트롤 위치를 실질적으로 명확히 하는 경우에만 사용하세요. 페이지가 이미지 없이 사용 가능하도록 지침과 기타 필수 정보를 텍스트에 유지하세요.

모든 스크린샷은 최신이어야 하며 페이지의 특정 목적을 위해 캡처되어야 합니다. 관련 화면과 상태를 설명하는 대체 텍스트를 제공하세요. 다른 기여자가 캡처를 재현할 수 있도록 픽스처, 라우트, 뷰포트, 로케일, 테마를 기록하세요.

코드 샘플

코드 샘플은 주변 산문만큼 중요합니다.

모든 코드 블록을 블록이 무엇을 하는지 독자에게 알려주는 완전하고 독립적인 문장으로 자체 줄에 도입하세요. 콜론으로 끝나는 문장 조각, 빈 제목 또는 “다음과 같이:“로 시작하지 마세요.

✅ 다음 예시는 sandboxed 배열에 플러그인을 등록합니다:

❌ 다음과 같이 플러그인을 추가하세요:

도입은 독자에게 코드가 무엇을 하는지 준비시켜, _어떻게_만 파악하면 됩니다. 또한 약간 다른 작업을 하는 독자를 위한 빈칸 채우기 패턴을 만듭니다.

<Steps> 절차 내에서는 직접적인 명령형 지시가 도입입니다 (“tsconfig.json을 추가하세요:” 다음에 파일이 오는 것은 번호 매긴 단계에서 괜찮습니다).

기타 규칙:

실제 작동하는 코드를 사용하세요. foo/bar는 없습니다. 가능한 모든 값이 아닌 하나의 현실적인 구성을 보여주세요 — 독자는 하나만 가질 것입니다.
파일을 나타내는 모든 블록에 title= 파일명을 추가하세요, 독자가 코드가 어디에 들어가는지 알 수 있도록.
```
```ts title="src/plugin.ts"
```
전후 변경에는 원시 ```diff 펜스가 아닌 Expressive Code 주석을 사용하세요. 변경된 줄은 del={n} / ins={n}으로, 변경된 텍스트는 del="…" / ins="…"으로 표시하세요. diff를 변경되는 줄에 최소한으로 유지하세요.

다음 예시는 단일 줄 변경을 보여줍니다:
```
```ts del={1} ins={2}
import { definePlugin } from "emdash";
import type { SandboxedPlugin } from "emdash/plugin";
```
```
제출 전에 로컬에서 렌더링된 코드를 미리 보세요. 오타가 표시를 깨뜨릴 수 있습니다.

업그레이드 및 마이그레이션 가이드

기존 프로젝트를 새 버전으로 이동하는 것을 돕는 가이드는 고정된 구조를 따릅니다. “무엇을 해야 하나요?” 섹션은 독자가 가장 가치를 두는 부분입니다 — 아끼지 마세요.

다음으로 시작하세요: 업그레이드 방법, “그냥 동작할” 수 있지만 그렇지 않으면 계속 읽으라는 메모, 변경 로그 링크.

그런 다음 각 호환성 깨는 변경을 자체 항목으로 나열하세요:

### [이름 변경/변경/제거/사용 중단]: <기능>

이전 버전에서는, <한 문장, 과거형, 무엇을 했는지>.

<한 문장, 현재형, 지금 어떻게 작동하는지>.

#### 무엇을 해야 하나요?

<명령형 동작: 업데이트… / 교체… / 제거…, 최소 diff 포함.>

독자가 영향을 어떻게 느끼는지에 따라 동사를 선택하세요. 새 기본값이 값을 대체하면 “변경: 기본값”이지 “추가: 옵션”이 아닙니다.

호환성 깨는 변경은 독자의 프로젝트에 변경이 필요하거나 작동이 중단되는 것입니다. 사실만이 아닌 동작을 제공하세요. “Node.js의 최소 버전은 이제 X입니다”가 아니라 “다음 명령으로 Node.js 버전을 확인하고 X 미만이면 업그레이드하세요”.

EmDash 고유 사항

반복되는 상황에 대한 규약, 기여자가 얼마나 자주 접하는지 순서로 정렬. 이것은 규약 목록이지, 어떤 기능이 더 중요한지의 순위가 아닙니다.

플러그인: 샌드박스 vs 네이티브

샌드박스와 네이티브 플러그인은 서로 다른 작성 형태를 가진 다른 형식입니다. 하나의 변경이 다른 것에 영향을 미치는 경우는 드뭅니다. 페이지나 예시가 어떤 형식에 대한 것인지 명시하세요. 샌드박스 플러그인 페이지를 편집할 때 네이티브 플러그인 예시를 변경하지 마세요. 그 반대도 마찬가지입니다.

지역화

문서 PR에 messages.po 변경을 포함하지 마세요. 워크플로우가 main으로 병합 시 카탈로그를 추출합니다. 포함하면 불필요한 변경과 병합 충돌이 발생합니다.

실험적 기능

실험적 플래그 뒤에 있는 기능이나 RFC 하의 불안정한 와이어 포맷은 예고 없이 변경될 수 있습니다. 문서를 가볍게 유지하고, 주의 <Aside>로 표시하고, RFC 또는 토론을 진실의 출처로 가리키세요. 불안정한 서피스를 상세히 문서화하지 마세요.

Atmosphere 계정

Bluesky와 더 넓은 AT Protocol 네트워크 뒤에 있는 휴대 가능하고 사용자 소유의 신원이 나올 때, Atmosphere 계정이라고 부르고 일관되게 그 용어를 사용하세요. 첫 번째 언급을 Atmosphere 로그인 가이드 또는 atmosphereaccount.com에 링크하세요. did:plc:…와 핸들은 구체적인 식별자입니다; 리터럴 값이 필요할 때 사용하세요.

문서는 코드입니다

문서 사이트는 EmDash 인접 Astro 프로젝트입니다. 문서 변경은 코드와 동일한 풀 리퀘스트 및 리뷰 플로우를 거칩니다. 모든 텍스트 변경은 리뷰를 기다립니다; 문구 변경은 문장의 의미를 바꾸거나 사이트의 다른 곳에서 맞는 편집이 필요할 수 있습니다. 작고, 리뷰되고, 일관된 변경이 전체 사이트를 일관되게 유지합니다.