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

이 가이드는 EmDash 문서가 어떻게 작성되는지 정의합니다. 기여는 이에 맞게 편집됩니다. 이것을 암기할 필요는 없습니다. 검토자와 편집자가 도와줄 것입니다. 그러나 이를 따르면 기여가 더 빨리 병합됩니다.

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

가독성

다음을 선호하십시오:

짧은 문장과 짧은 단락.
전문 용어보다 평범한 어휘.
약어와 두문자어를 처음에 완전히 작성.
긴 구절을 나누기 위한 제목과 목록.
능동태.

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

EmDash가 아닌 주제(TypeScript, AT 프로토콜, 웹 폰트, 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"
```
Expressive Code 주석을 사용하십시오. 이전/이후 변경에 대한 원시 ```diff 펜스가 아닙니다. del={n} / ins={n}로 변경된 줄을 표시하거나 del="…" / ins="…"로 변경된 텍스트를 표시하십시오. diff를 최소화하고 변경되는 줄에 로컬로 유지하십시오.

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

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

기존 프로젝트를 새 버전으로 이동하는 데 독자를 돕는 가이드는 고정된 구조를 따릅니다. “무엇을 해야 합니까?” 섹션은 독자가 가장 가치 있게 여기는 부분입니다. 여기에 인색하지 마십시오.

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

그런 다음 각 주요 변경 사항을 자체 항목으로 나열합니다:

### [Renamed/Changed/Removed/Deprecated]: <feature>

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

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

#### 무엇을 해야 합니까?

<명령형 작업: 업데이트… / 교체… / 제거…, 최소한의 diff로.>

독자가 영향을 느끼는 방식에 따라 동사를 선택하십시오. 새 기본값이 값을 대체하는 경우 “Changed: default value”이지 “Added: option”이 아닙니다.

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

EmDash 세부 사항

반복되는 상황에 대한 규칙, 기여자가 만나는 빈도로 정렬됩니다. 이것은 규칙 목록이지 어떤 기능이 중요한지에 대한 순위가 아닙니다.

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

샌드박스 및 네이티브 플러그인은 다른 저작 형태를 가진 다른 형식입니다. 하나에 대한 변경은 다른 것에 거의 영향을 미치지 않습니다. 페이지 또는 예제가 어떤 형식에 관한 것인지 명시하십시오. 샌드박스 플러그인 페이지를 편집할 때 네이티브 플러그인 예제를 변경하지 마십시오. 그 반대도 마찬가지입니다.

지역화

문서 PR에 messages.po 변경 사항을 포함하지 마십시오. 워크플로는 main에 병합할 때 카탈로그를 추출합니다. 포함하면 혼란과 병합 충돌이 발생합니다.

실험적 기능

실험적 플래그 뒤에 있는 기능 또는 RFC 하의 불안정한 와이어 형식은 예고 없이 변경될 수 있습니다. 문서를 간결하게 유지하고, 주의 <Aside>로 플래그를 지정하고, RFC 또는 토론을 진실의 원천으로 가리키십시오. 불안정한 표면을 세부적으로 문서화하지 마십시오.

Atmosphere 계정

Bluesky와 더 넓은 AT 프로토콜 네트워크 뒤의 휴대 가능하고 사용자 소유의 신원이 나타나면 Atmosphere 계정이라고 부르고 그 용어를 일관되게 사용하십시오. 첫 번째 언급을 Atmosphere 로그인 가이드 또는 atmosphereaccount.com에 연결하십시오. did:plc:… 및 핸들은 구체적인 식별자입니다. 리터럴 값이 필요한 곳에서 사용하십시오.

문서는 코드입니다

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