문서 스타일 가이드
이 페이지는 Backstage 문서에 대한 작성 스타일 지침을 제공해요.
출처: 문서
본문
이 페이지는 Backstage 문서에 대한 작성 스타일 지침을 제공해요. 이는 지침이지 규칙이 아니에요. 여러분의 최선의 판단을 사용하고, 이 문서에 대한 변경 사항을 풀 리퀘스트로 제안해도 좋아요.
문서 기여에 대한 추가 정보는 기여자 가이드(Contributors Guide)를 참고하세요.
언어
Backstage 문서는 미국 영어(U.S. English) 철자와 문법을 사용해요.
문서 사이트는 Docusaurus로 구축되며, admonition 같은 일부 Docusaurus 특유의 기능과 함께 표준 Markdown을 사용해요.
어조
Backstage 문서는 친근하고 전문적이며 도움이 되는 느낌이어야 해요. 주제에는 새롭지만 소프트웨어 개발 자체는 낯설지 않은 동료에게 설명하는 유능한 동료처럼 글을 쓰세요.
- 친절하되 편하지는 않게. 속어, 번역되지 않을 수 있는 유머, 지나치게 열정적인 언어는 피하세요. 따뜻하고 직설적인 어조가 가장 잘 작동해요.
- 독자의 시간을 존중하세요. 핵심으로 바로 가세요. 개념에 더 긴 설명이 필요하면 제공하되, 내용을 잡담으로 채우지 마세요.
- 격려하되 가르치는 듯한 말투를 피하세요. 독자가 유능하다고 가정하세요. "as everyone knows", "obviously" 같은 표현은 피하세요.
- 포용적이게. 성별 중립적인 언어를 사용하세요. 전 세계적으로 이해되지 않을 수 있는 문화적 언급은 피하세요. 국제적인 독자를 위해 글을 쓰세요.
- 정확하게. Backstage 개념에 대한 올바른 기술 용어를 사용하세요. 새 용어를 소개할 때는 첫 사용 시점에 정의하세요.
문서 형식 표준
UI 요소에는 굵게 사용
| Do | Don't | |
|---|---|---|
| Click Fork. | Click "Fork". | |
| Select Other. | Select "Other". |
새 용어를 정의하거나 소개할 때는 이탤릭 사용
| Do | Don't | |
|---|---|---|
| A plugin is a modular extension ... | A "plugin" is a modular extension ... | |
| These components form the backend system. | These components form the "backend system". |
파일명, 디렉터리, 경로에는 코드 스타일 사용
| Do | Don't | |
|---|---|---|
Open the app-config.yaml file. |
Open the app-config.yaml file. | |
Go to the /plugins directory. |
Go to the /plugins directory. | |
Open the packages/backend/src/index.ts file. |
Open the packages/backend/src/index.ts file. |
인라인 코드와 명령에는 코드 스타일 사용
| Do | Don't | |
|---|---|---|
The yarn start command starts the app. |
The "yarn start" command starts the app. | |
Run yarn install from the project root. |
Run "yarn install" from the project root. | |
Use single backticks to enclose inline code, for example const x = true. |
Use bold or italics for inline code, for example const x = true. | |
| Enclose code samples with triple backticks. | Enclose code samples with any other syntax. | |
| Use meaningful variable names that have context. | Use variable names such as foo, bar, and baz. |
패키지 이름과 API 참조에는 코드 스타일 사용
| Do | Don't | |
|---|---|---|
Install the @backstage/core-plugin-api package. |
Install the @backstage/core-plugin-api package. | |
The createRouter function creates a new router. |
The createRouter function creates a new router. | |
Set the value of the backend.baseUrl field in the config file. |
Set the value of the "backend.baseUrl" field in the config file. |
자리표시자에는 꺾쇠 괄호 사용
자리표시자에는 꺾쇠 괄호를 사용하세요. 자리표시자가 무엇을 나타내는지 독자에게 알려주세요. 예를 들어:
yarn workspace @backstage/plugin-<plugin-name> start
따옴표 안의 구두점에는 국제 표준 사용
| Do | Don't | |
|---|---|---|
| Events are recorded with an associated "stage". | Events are recorded with an associated "stage." | |
| The copy is called a "fork". | The copy is called a "fork." |
코드 스니펫 형식
명령 프롬프트는 포함하지 말 것
| Do | Don't | |
|---|---|---|
yarn install |
$ yarn install |
명령과 출력을 분리할 것
앱이 실행 중인지 확인하세요:
yarn start
출력은 이와 비슷해요.
[0] webpack output is served from /
[1] Loaded config from app-config.yaml
코드 블록에 적절한 언어 태그 사용
펜스 코드 블록에 올바른 언어 식별자를 사용하세요. TypeScript에는 ts 또는 typescript, YAML 구성에는 yaml, 셸 명령에는 shell, 명령 출력에는 log, 프롬프트와 출력이 섞인 트랜스크립트에는 shell-session, 체인지셋에는 diff를 사용하세요. 디렉터리 트리처럼 다르게 분류할 것이 없을 때는 text를 사용하세요.
모든 식별자는 Prism이 인식하는 언어여야 하며, Docusaurus가 기본으로 번들하는 집합 밖에 있는 것은 microsite/docusaurus.config.ts의 additionalLanguages에 나열해야 해요. 인식되지 않는 식별자는 오류가 아니에요. 다만 블록이 문법 하이라이팅을 잃을 뿐인데, 이는 놓치기 쉬워요.
Admonitions
Backstage 문서는 콜아웃에 Docusaurus admonitions를 사용해요. 상황에 맞게 :::note, :::tip, :::caution, :::danger를 사용하세요.
:::note
You can use _Markdown_ inside admonitions.
:::
참고
Admonition 안에서 Markdown을 사용할 수 있어요.
보충 정보에는 :::note, 유용한 제안에는 :::tip, 잠재적 함정에는 :::caution, 데이터 손실이나 보안 문제를 일으킬 수 있는 동작에는 :::danger를 사용하세요.
Admonition에 사용자 지정 제목을 주려면 제목을 대괄호 안에 넣으세요. 타입 뒤에 괄호 없이 제목을 쓰는 것은 더 이상 작동하지 않으며, admonition이 대신 일반 텍스트로 렌더링돼요.
:::tip[Browser window didn't open]
Navigate to `http://localhost:3000` yourself.
:::
타입이 이미 말하지 않은 것을 알려줄 때만 제목을 추가하세요. Note라는 제목의 :::note는 잡음일 뿐이니 붙이지 마세요.
Admonition을 짧고 집중되게 유지하세요. 각 admonition은 하나의 명확한 요점을 담아야 해요. Admonition 안에 여러 단락을 쓰고 있다면 그 내용이 본문에 속하는지 고려해보세요.
여러 admonition을 연속으로 쌓는 것은 피하세요. 페이지에 콜아웃이 너무 많으면 그 효과가 희석되고 내용을 읽기 어려워져요. 한 섹션에 admonition이 둘 이상 있으면 대부분의 정보가 일반 단락에 있도록 내용을 재구성하세요.
아코디언(Accordions)
HTML <details>와 <summary> 요소를 사용해 접을 수 있는 섹션을 만드세요. 이는 "Common issues" 섹션, 긴 참조 표, 읽기 흐름을 깨뜨릴 보충 콘텐츠에 유용해요.
<details>
<summary>Summary text visible when collapsed</summary>
Content inside the accordion. You can use **Markdown** here, including code
blocks, lists, and other formatting.
</details>
요약 텍스트(접었을 때 보이는 부분)
아코디언 안의 콘텐츠. 여기서 **Markdown**을 사용할 수 있어요. 코드 블록, 목록, 기타 형식을 포함해요.<summary> 태그 뒤와 닫는 </details> 태그 앞에 빈 줄을 남겨 Markdown 콘텐츠가 안에서 올바르게 렌더링되도록 하세요.
<summary> 요소 안의 인라인 코드에는 HTML <code> 태그 대신 백틱을 사용하세요. 백틱은 summary 요소 안에서 올바르게 렌더링되고 소스를 나머지 Markdown 콘텐츠와 일관되게 유지해줘요.
Markdown 요소
줄바꿈
헤딩, 목록, 이미지, 코드 블록 같은 블록 수준 콘텐츠를 구분하려면 단일 줄바꿈 하나를 사용하세요. Markdown 소스에서는 단락을 합리적인 줄 길이로 직접 줄바꿈하세요. 이렇게 하면 diff를 더 쉽게 검토할 수 있고 다운스트림 지역화에도 도움이 돼요.
헤딩과 제목
| Do | Don't | |
|---|---|---|
| Use ordered headings to provide a meaningful outline of your content. | Use headings level 4 through 6 unless absolutely necessary. | |
| Use sentence case for headings. For example, Extend the catalog model | Use title case for headings. For example, Extend The Catalog Model | |
Use pound signs (#) for headings. |
Use underlines (--- or ===) for headings. |
단락
| Do | Don't | |
|---|---|---|
| Try to keep paragraphs under 6 sentences. | Write long, unbroken walls of text. | |
Use three hyphens (---) for horizontal rules when needed. |
Use horizontal rules for decoration. |
링크
| Do | Don't | |
|---|---|---|
| Write hyperlinks with descriptive text. For example: See Getting Started for details. | Use ambiguous link text. For example: See here for details. | |
Write Markdown-style links: [link text](./index.md). |
Write HTML-style links or create links that open in new tabs. | |
Give a plain address some markup: <https://example.com>. |
Paste a bare address: https://example.com. |
설명 텍스트가 있는 링크는 쓸 수 있다면 항상 더 나은 선택이에요. 화면 낭독기를 사용하는 사람들은 링크를 나열해 페이지를 탐색하는 경우가 많아요. 그래서 the Kubernetes configuration 같은 링크 텍스트는 어디로 가는지 알려주는 반면, 원시 주소는 그렇지 않아요.
주소 자체를 표시하고 싶을 때 구문은 파일 확장자에 따라 달라져요. .md 파일에서는 꺾쇠 괄호나 Markdown 링크를 사용하세요. .mdx 파일에서는 Markdown 링크를 사용하세요. 꺾쇠 괄호는 거기서 유효하지 않으며 빌드가 실패해요.
목록
- 목록의 항목 중 하나 이상이 완전한 문장이라면 각 항목을 마침표로 끝내세요. 일관성을 위해 모든 항목이 완전한 문장이거나 그 어느 것도 완전한 문장이 아니어야 해요.
- 순서 있는 목록에는 숫자 하나(
1.)를 사용하세요. - 순서 없는 목록에는 (
-)를 사용하세요. - 각 목록 뒤에는 빈 줄을 남기세요.
- 중첩 목록은 두 칸 들여쓰기하세요.
- 일련의 단계에는 "First", "Then", "Finally"가 있는 산문보다 번호 목록을 사용하세요. 번호 목록은 훑어보기 쉽고 순서를 명시하며 독자에게 특정 단계를 참조할 명확한 방법을 줘요.
| Do | Don't | |
|---|---|---|
| 1) Install the package. 2) Run the migration. 3) Start the server. | First, install the package. Then, run the migration. Finally, start the server. |
표
명확한 열 헤더가 있는 Markdown 표를 사용하세요. 표 내용은 간결하게 유지하세요. 정형 데이터가 많은 양일 경우에는 목록이나 별도의 하위 섹션을 대신 고려하세요.
콘텐츠 모범 사례
약어는 첫 사용 시 전체를 표기
약어를 사용할 때는 첫 사용 시점에 전체를 표기한 뒤 괄호 안에 약어를 쓰세요. 그 후에는 약어만 사용해도 돼요.
| Do | Don't | |
|---|---|---|
| Software Development Kit (SDK) | SDK (without ever defining it) | |
| Role-Based Access Control (RBAC) ... configure RBAC ... | RBAC ... configure RBAC ... | |
| Hyper Text Markup Language (HTML) | HTML (on first use without expansion) |
예외: URL, API, HTML 같은 보편적으로 이해되는 약어는 소프트웨어 개발자라는 대상 독자에게 상식이라면 전체를 표기할 필요가 없어요.
현재 시제 사용
| Do | Don't | |
|---|---|---|
| This command starts a proxy. | This command will start a proxy. | |
| The plugin provides a catalog page. | The plugin will provide a catalog page. |
예외: 올바른 의미를 전달하는 데 필요하다면 미래 시제나 과거 시제를 사용하세요.
능동태 사용
| Do | Don't | |
|---|---|---|
| You can explore the API using a browser. | The API can be explored using a browser. | |
| The YAML file specifies the base URL. | The base URL is specified in the YAML file. |
예외: 능동태가 어색한 구문으로 이끌면 수동태를 사용하세요.
단순하고 직접적인 언어 사용
| Do | Don't | |
|---|---|---|
| To create a plugin, ... | In order to create a plugin, ... | |
| See the configuration file. | Please see the configuration file. | |
| View the catalog entities. | With this next command, we'll view the catalog entities. |
독자를 "you"로 지칭
| Do | Don't | |
|---|---|---|
| You can create a plugin by ... | We'll create a plugin by ... | |
| In the preceding output, you can see ... | In the preceding output, we can see ... |
라틴어 표현 피하기
라틴어 약어보다 영어 용어를 선호하세요.
| Do | Don't | |
|---|---|---|
| For example, ... | e.g., ... | |
| That is, ... | i.e., ... |
예외: "and so on"에는 "etc."를 사용하세요.
피해야 할 패턴
"we"를 의도적으로 사용
"we"는 "당신과 내가 함께 이 작업을 진행하는 것"을 의미하는 튜토리얼과 워크스루에서는 좋아요. "we"가 Backstage 프로젝트, 유지보수자, 아니면 독자의 팀을 가리키는지 불분명할 때는 피하세요.
| Ok | Avoid | |
|---|---|---|
| Next, we need to add the backend package. | We provide a new feature ... | |
We can verify this by running yarn start. |
In version 1.25, we have added ... |
전문 용어와 관용구 피하기
일부 독자는 영어를 제2언어로 사용해요. 그들이 더 잘 이해하도록 전문 용어와 관용구를 피하세요.
| Do | Don't | |
|---|---|---|
| Internally, ... | Under the hood, ... | |
| Create a new plugin. | Spin up a new plugin. |
미래에 대한 진술 피하기
미래에 대한 약속이나 힌트를 피하세요. 실험적 기능에 대해 이야기해야 한다면 명확히 그렇게 표시하세요.
곧 낡아질 진술 피하기
"currently", "new" 같은 단어를 피하세요. 오늘 새로운 기능이 몇 달 후에도 새롭게 여겨지지 않을 수 있어요.
| Do | Don't | |
|---|---|---|
| In version 1.25, ... | In the current version, ... | |
| The search feature provides ... | The new search feature provides ... |
특정 이해 수준을 가정하는 단어 피하기
"just", "simply", "easy", "easily", "simple" 같은 단어를 피하세요. 이 단어들은 가치를 더하지 않아요.
| Do | Don't | |
|---|---|---|
| Include one command in ... | Include just one command in ... | |
| Run the container ... | Simply run the container ... | |
| You can remove ... | You can easily remove ... | |
| These steps ... | These simple steps ... |
Backstage 단어 목록
사이트 전반에 걸쳐 일관되게 사용해야 하는 Backstage 특유의 용어와 단어 목록이에요.
| Term | Usage | |
|---|---|---|
| Backstage | Always capitalized. | |
| plugin | Lowercase when referring to the concept. Use code style when referring to a specific package, for example @backstage/plugin-catalog. |
|
| Software Catalog | Capitalized as a product name. Use "catalog" (lowercase) when referring to the concept generically. | |
| Software Templates | Capitalized as a product name. | |
| TechDocs | One word, camel case. | |
| Scaffolder | Capitalized as a product name. | |
| app-config | Use code style: app-config.yaml. |
|
| open source | Two words, lowercase (unless starting a sentence). | |
| backend system | Lowercase when referring to the Backstage backend framework. |
일반 단어 목록
사이트 전반에 걸쳐 일관되게 사용해야 하는 일반 용어와 단어 목록이에요.
| Term | Usage | |
|---|---|---|
| GitHub | Use GitHub in documentation. In code, use github (lowercase). |