> ## Documentation Index
> Fetch the complete documentation index at: https://docs.optimism.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 스타일 가이드

> 일관된 문체, 어조, 스타일로 Optimism Docs의 기술 콘텐츠를 작성하는 방법을 설명합니다.

이 가이드는 일관된 문체, 어조, 스타일을 사용하여 Optimism Docs의 기술 콘텐츠를 작성하는 방법을 설명합니다.

이 스타일 가이드는 Optimist들이 일관된 문체, 어조, 스타일로 기술 콘텐츠를 작성할 수 있도록 돕는 것을 목표로 합니다. 기술 문서와 Optimism 전반에서 자주 사용되는 단어, 용어, 개념을 알파벳순으로 정리한 목록은 [용어집](https://docs.optimism.io/op-stack/reference/glossary.md)을 참고하십시오.

이 문서가 모든 질문이나 사용 사례를 다루지는 않습니다. 이 가이드는 [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/)를 기반으로 합니다. 여기에서 다루지 않는 사용 사례나 상황은 해당 가이드를 참고하십시오.

이 가이드는 **어떻게** 작성하는지(문체, 어조, 서식, 구조)를 다룹니다. docs.optimism.io에 **어떤** 콘텐츠가 들어가야 하는지, 즉 각 콘텐츠 유형의 정식 위치와 서드파티 콘텐츠를 표시하는 방법은 [콘텐츠 가이드](https://docs.optimism.io/ko/op-stack/contribute/content-guide.md)를 참고하십시오.

* 문서 관련 질문, 의견 또는 지원이 필요하면 [Optimism monorepo](https://github.com/ethereum-optimism/optimism/issues)에 이슈를 생성하십시오.

## 목차

* [파일, 폴더 및 명명 규칙](#files-folders-and-naming-conventions)
* [작성 스타일](#writing-style)
* [접근성](#accessibility)
* [콘텐츠 구성](#content-organization)
* [링크](#links)
* [콘텐츠 유형](#content-types)
* [일반 서식](#general-formatting)

## 파일, 폴더 및 명명 규칙

### 폴더 구조

[docs.optimism.io](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs) 저장소의 폴더 구조는 여러 상위 카테고리로 구성되어 있습니다.

왼쪽 사이드바(사이드 내비게이션)는 `docs.json` 파일에서 관리하며, 이 파일은 페이지를 추가하거나 삭제할 때만 수정해야 합니다. 콘텐츠가 계속 업데이트되므로 자주 수정하면 merge 충돌이 발생할 수 있습니다. PR을 커밋할 때는 다른 사람의 변경 사항을 수락하십시오.

새 주제를 왼쪽 사이드바의 어디에 배치해야 할지 확실하지 않아도 걱정하지 마십시오. 최선을 다해 배치하고 PR을 제출하면 Developer Relations 팀이 `docs.json` 파일을 수정하여 적절한 위치를 결정합니다.

오른쪽 사이드바(페이지 목차)는 페이지의 모든 H2 및 H3 제목을 기준으로 자동 생성됩니다.

### 파일 이름

일반적으로 파일 이름은 가능한 한 짧게(약 2\~4단어) 작성하고 모두 소문자로 작성해야 합니다. 각 단어 사이에는 하이픈(-)을 넣습니다.

**예시:** `writing-a-guide.mdx` 또는 `run-node.mdx`

### 파일 경로

문서 페이지 **안에서** 파일 경로를 언급할 때는 가독성을 위해 코드 스니펫 형식으로 작성하고 백틱으로 감싸야 합니다.

**예시**: `/source/docs/assets/images/`

## 작성 스타일

### 문체와 어조

친근하면서도 전문적인 어조로 작성하십시오. 우리는 Optimism의 발전에 대해 긍정적이고, 해박하며, \*\*낙관적(optimistic)\*\*이며, 이러한 태도를 기술 문서에 최대한 담아내려고 합니다.

### 명확하고 간결한 언어

* 일관성을 유지하십시오. 문서 전체에서 동일한 용어, 문체, 어조를 사용합니다.
* 간결하게 작성하십시오. 핵심 정보 제공에 집중하고 불필요한 정보는 포함하지 마십시오.
* 독자가 이해할 수 있는 언어를 사용하십시오. web3 분야에서 전문 용어를 피하기는 어렵지만, 다음과 같은 전략으로 이해도를 높일 수 있습니다.
  * 용어를 사용하기 전에 용어집에서 해당 용어가 명확하게 정의되어 있는지 확인하기
  * 용어집을 정기적으로 업데이트하기
* 행동 중심의 스타일로 작성하십시오. 능동태로 작성하여 사용자가 당면한 작업을 완료하도록 돕는 데 집중합니다. 능동태는 더 직접적이며 모호함을 줄여 줍니다. 수동태는 모호하고 어색한 문장을 만드는 경우가 많으므로 피하십시오.
* 특정 성별을 가리키는 표현을 피하십시오. 명령형을 사용하십시오. 명령형을 사용하면 3인칭(him, her, she, his) 대신 2인칭(you, your)을 사용할 수 있습니다.

### 대소문자 표기

페이지 제목, 헤딩, 본문 콘텐츠, 링크 텍스트 등 문서 전체에서 sentence case를 사용하십시오.

* 모두 대문자로 쓰는 것은 읽기 이해 속도를 떨어뜨리므로 피하십시오.

* 문장 안의 고유 명사는 대문자로 시작하십시오.
  **예시**: I use Visual Studio on my local machine.

* 페이지 제목과 모든 헤딩(H1, H2, H3)에는 sentence case를 사용하십시오. 첫 단어와 OP Stack, OP Mainnet, Ethereum, Standard Bridge 같은 고유 명사만 대문자로 시작합니다. op-node 같은 컴포넌트 이름은 헤딩의 첫머리에 오더라도 소문자로 유지하십시오.

  > **sentence case 헤딩 예시:**
  >
  > * Configure the batcher
  > * How L1 reorgs propagate to L2
  > * OP Stack finality

* 버튼, 탭 이름 또는 기타 인터페이스 요소를 언급할 때는 인터페이스에 표시된 대소문자를 그대로 따르고 이름을 굵게 표시하십시오.

  > **예시:**
  >
  > * **Make Owner**를 선택합니다.
  > * **Clear Caches**를 클릭합니다.
  > * **Settings** 탭을 선택합니다.

* 본문 콘텐츠와 짧은 구절에는 링크인 경우에도 sentence case를 사용하십시오. sentence case란 문장의 첫 글자만 대문자로 쓰는 것을 의미합니다.
  **예시:** 노드 운영자로서 특정 작업을 수행하는 방법을 찾고 있다면 튜토리얼 모음을 검색하거나 [새 튜토리얼을 제안](https://github.com/ethereum-optimism/optimism/issues)할 수 있습니다.

* 코드 스니펫에서는 기본적으로 소문자를 사용하십시오. 단, 코드 블록에서 대문자를 사용하고(예: 함수나 변수의 이름) 기술 문서의 다른 곳에서 해당 함수나 변수를 언급하는 경우는 예외입니다.
  **예시**: `git add` 실행 또는 `useState` 가져오기

  > 확실하지 않을 때는 코드베이스를 따르십시오. 코드가 컴파일되려면 대소문자가 정확해야 하기 때문입니다.

## 접근성

콘텐츠를 작성할 때는 스크린 리더 사용자, 시각 장애가 있는 사람, 마우스나 키보드를 사용하는 사람 모두가 접근할 수 있도록 하십시오. 접근성 가이드라인에 대한 자세한 내용은 [W3C Web Content Accessibility Guidelines 2.0](http://www.w3.org/TR/UNDERSTANDING-WCAG20/Overview.html#contents)을 참고하십시오.

### 대체 텍스트

* 스크린 리더가 이미지의 목적을 해석하여 사용자에게 전달할 수 있도록 모든 이미지에 대체 텍스트(alt text)를 제공하십시오. 스크린 리더가 사용자에게 읽어 줄 수 있도록 대체 텍스트에는 이미지에 표시된 모든 내용이 포함되어야 합니다.
* 삽입된 동영상 콘텐츠나 iframe의 title 속성을 수정하여 동영상에 대체 텍스트를 제공하십시오. title 속성은 스크린 리더에 설명 정보를 제공하는 대체 텍스트 역할을 합니다. 말하기나 내레이션이 포함된 동영상 콘텐츠에는 반드시 자막(closed caption)이 포함되어야 합니다.

### 캡션

* 가능하면 시각적 요소/객체에 캡션을 제공하여 능력과 관계없이 모든 사용자가 시각 자료에 접근할 수 있도록 하십시오. 여기에는 이미지나 스크린샷, 애니메이션 GIF, 홍보 및 튜토리얼 동영상, 표, 차트, mermaid 다이어그램, 코드 블록이 포함됩니다.
* 캡션을 주요 언어로 번역할 수 있도록 하십시오.

### 이미지

* 텍스트, 코드 샘플 또는 터미널 출력을 이미지로 사용하지 마십시오. 실제 텍스트를 사용하십시오.
* 가능하면 PNG 대신 SVG를 사용하십시오. SVG는 사용자가 이미지를 확대해도 선명하게 유지됩니다.

## 콘텐츠 구성

우리는 사용자 중심적이고 접근하기 쉬운 일관된 구성을 지향합니다. 이를 위해서는 길고 빽빽한 단락 대신 기술 콘텐츠를 섹션으로 묶는 의도적인 작업과 계획이 필요합니다. 이렇게 하면 사용성 관점에서 독자에게 시각적 휴식을 제공하고 읽기 이해도도 향상됩니다.

* 구조화된 헤딩(H1, H2 또는 #, ##)을 사용하여 독자가 기술 문서를 따라갈 수 있도록 안내하십시오.
* 시간 순서대로 진행되는 단계에는 번호 목록을 사용하십시오.
* 특정 순서가 필요하지 않은 콘텐츠를 시각적으로 구분할 때는 글머리 기호 목록을 사용하십시오.
* 최적의 가독성을 위해 텍스트 서식(굵게 vs. 기울임꼴)을 지정하십시오. 웹 콘텐츠에서 기울임꼴은 가독성을 떨어뜨리므로 피하십시오. 예를 들어 기술 문서에서 특정 버튼이나 페이지 이름을 언급할 때는 **굵게**를 사용하는 것이 적절합니다.
* 기술 콘텐츠는 한 번에 하나의 주요 개념이나 작업만 다루도록 구성하십시오.
  * **일반적인 경험 법칙**: 구조화된 헤딩이 3단계를 넘거나(H4 또는 ####) 예상 읽기 시간(ERT)이 20분을 넘는 문서는 수정이 필요하며, 일반적으로 간결하게 편집하거나 문서를 여러 페이지로 나누거나 둘 다 수행합니다.
  * 수정 작업에는 보통 간결하게 편집하거나, 문서를 여러 페이지로 나누거나, 이 두 가지를 조합하는 작업이 필요합니다.
* 독자의 다양한 요구와 사전 지식을 기준으로 콘텐츠를 구성하십시오. 작업을 완료하거나 개념을 이해하는 데 사전 지식이 필요하다면 이를 사용자와 공유하여(더 알아볼 수 있는 링크 포함) 사용자가 쉽게 따라잡을 수 있도록 하십시오.

### 메타 태그

* 문서의 SEO 순위를 높이기 위해 각 페이지에 메타 **title**, **language**, **description**을 정의하십시오. 메타 태그는 페이지 상단의 H1 태그 앞에 배치하고, 텍스트 블록의 양쪽을 대시 3개로 감쌉니다.

* 메타 title은 H1 페이지 제목을 재사용하여 설정하십시오. 다만 메타 title은 사용자에게 페이지상으로 표시되지 않으므로 H1 페이지 제목도 반드시 필요합니다.

  > **참고:** SEO 가이드라인은 메타 페이지 제목을 H1 페이지 제목과 약간 다르게 작성할 것을 권장하지만, 이는 사이트 플랫폼에서 자동으로 처리합니다. 따라서 문서 작성의 편의를 위해 H1 페이지 제목을 메타 페이지 제목과 일치시키십시오.

* 접근성과 사용성(스크린 리더용)을 위해, 그리고 향후 언어 현지화 지원을 쉽게 활성화할 수 있도록 language 속성을 설정하십시오.

* 메타 description은 페이지의 가장 관련성 높은 콘텐츠를 간결하게 요약(100\~150자)하여 작성하십시오.

> **문서의 메타 섹션 예시:**
>
> ```
> ---
> title: Supercharge Your App with Account Abstraction
> lang: en-US
> description: This guide explains how account abstraction enables users to utilize smart contracts to build, onboard, and scale apps.
> ---
> ```

### 페이지 제목(H1)

* 간결한 페이지 제목을 작성하고 H1 형식으로 지정하십시오. 제목은 1\~2줄 안에 들어가야 합니다.
* SEO 메타 태그에 페이지 제목을 정의하는 것과 별도로, 모든 페이지에는 H1 헤딩이 있어야 합니다.
* H1 헤딩은 페이지 제목 전용이므로 페이지의 다른 곳에서는 H1을 사용하지 마십시오.
* 튜토리얼과 빠른 시작 문서에는 동명사(gerund, "ing"로 끝나는 동사)로 시작하는 작업 기반 페이지 제목을 사용하십시오.
  **예시**: `Creating your own L2 rollup` 또는 `Running a node`

### 헤딩과 목차

* 문서의 헤딩이나 하위 헤딩에는 동명사("ing"로 끝나는 동사)가 아닌 명령형 동사를 사용하십시오. 헤딩은 H2 태그로, 하위 헤딩은 H3 태그로 표시해야 합니다.

* 먼저 주요 주제에 따라 페이지 콘텐츠의 개요를 작성하십시오. 이것이 헤딩(H2 태그)이 됩니다. 특정 카테고리에 속하는 하위 주제가 있다면 하위 헤딩(H3 태그)으로 표시하십시오.

  > **예시:**
  >
  > * (H1) Supporting OP Mainnet in your wallet (H1 페이지 제목은 "ing" 동사 어미를 사용)
  > * (H2) Connect to OP Mainnet (H2는 "ing" 동사 어미를 사용하지 않음)
  > * (H2) Locate canonical token addresses (두 번째 H2도 "ing" 동사 어미를 사용하지 않음)

* 헤딩을 논리적으로 사용하십시오. 사이트는 H2 및 H3 태그에 대한 앵커 링크를 자동으로 생성하여 오른쪽 열의 목차(TOC)에 배치합니다.

* 가이드 및 템플릿 페이지에서는 H4 이상의 수준을 피하십시오. 이 스타일 가이드의 다른 곳에서 언급했듯이, 구조화된 헤딩이 3단계를 넘는(H4 또는 ####) 기술 문서는 대개 명확성, 구성 또는 구조에 문제가 있음을 나타내므로 수정해야 합니다.

* H4 헤딩은 (현재) 용어집 항목 전용으로 예약되어 있습니다. 이렇게 표준화하면 향후 툴팁 등 용어집 기능을 문서 전체로 확장하기가 더 쉬워집니다.

### 사전 요구 사항 나열(시작하기 전에)

* 현재 작업을 계속하기 전에 사용자가 완료해야 하는 작업(예: 모듈 설치, 소프트웨어 업데이트 다운로드 등)이 있다면 문서 상단에 "시작하기 전에(Before you begin)" 섹션을 추가하십시오.
* "Before you begin"이라는 제목을 사용하고 H2 형식으로 지정하십시오. 이 섹션은 페이지 개요/소개 섹션 또는 목차 다음에 와야 합니다.
* 사용성을 돕는 링크를 포함하여 사용자가 완료해야 하는 모든 작업을 포함하십시오. 사전 요구 사항이 2개를 넘으면 글머리 기호 목록을 사용하십시오.

  > **예시:**
  > (H2) Before you begin
  > ApacheSolr 모듈을 활성화해야 합니다. 자세한 내용은 [Drupal.org](http://drupal.org/)의 [ApacheSolr](https://drupal.org/project/apachesolr) 페이지를 방문하십시오.

### 콜아웃

* 작업을 완료하는 데 필요한 정보나 특히 중요한 정보로 사용자를 안내할 때 콜아웃을 사용하십시오. 문서에 콜아웃을 추가할 때는 sentence case를 사용하십시오.
* 문제 유형에 따라 올바른 콜아웃 유형을 사용하십시오: a) 정보/일반, b) 경고, c) 오류. 문서 플랫폼은 4가지 콜아웃 유형을 지원합니다.
  * 기본 및 정보 콜아웃은 설치나 배포를 더 쉽게 해 주는 제안이나 모범 사례처럼 민감하지 않고 호환성을 깨뜨리지 않는 정보를 사용자와 공유하는 데 사용합니다.
  * 경고 콜아웃은 제품이나 코드가 지원 중단될 예정인 경우처럼 중요한 정보를 나타내는 데 사용해야 합니다.
  * 오류 콜아웃은 데이터가 영구적으로 삭제되거나 손실될 수 있는 경우처럼 되돌릴 수 없거나 호환성을 깨뜨리는 변경을 초래할 수 있는 심각한 문제에만 사용합니다.
* 콜아웃이 너무 많으면 독자가 혼란스러울 수 있으므로 꼭 필요한 경우에만 사용하십시오. **일반적인 경험 법칙:** 콜아웃이 2개를 넘는 페이지는 수정이 필요하거나, 가이드 콘텐츠의 정확성을 확인하기 위해 Optimism 개발자 또는 프로덕트 매니저와 논의해야 할 가능성이 높습니다.

### 코드 샘플

* 개념을 설명하는 데 도움이 되도록 가능한 한 자주 코드 샘플을 사용하십시오. 가이드나 튜토리얼에서 사용할 수 있으며, 개발자에게 유용하려면 모든 튜토리얼에 최소 하나의 코드 샘플이 있어야 합니다.
* 모든 코드는 백틱으로 감싸고 내장 구문 강조 표시를 사용해야 합니다. 대부분의 문서 플랫폼은 코드 블록 안에 올바르게 정의된 경우 구문 강조 표시를 자동으로 적용합니다.

**예시**: 다음 markdown 또는 MDX 파일은

```js theme={null}
console.log('hello, world')
```

적절한 구문 강조 표시와 함께 이 코드 스니펫을 `javascript`로 렌더링합니다.

* 가독성과 접근성을 더욱 높이려면 코드 블록에 다음과 같은 사용자 중심 옵션을 고려하십시오.
  * 코드 블록에 파일 이름 또는 제목 추가하기
  * 캡션 또는 설명 추가하기(위에 표시된 것처럼)
  * 코드 블록 안에 줄 번호 추가 또는 표시하기(문서 안에서 특정 코드 줄을 쉽게 참조)
  * 사용자의 주의를 특정 영역으로 끌기 위해 코드 블록의 줄이나 문자열 강조 표시하기

### 이미지, 스크린샷 및 아이콘

* 이미지, 스크린샷, 아이콘은 루트 폴더의 `public/img` 디렉터리에 저장됩니다.
* 모든 이미지와 스크린샷에는 설명이 담긴 대체 텍스트가 있어야 합니다.
* 스크린샷은 가이드나 튜토리얼에서 다루는 콘텐츠를 명확하게 담아야 합니다.
  * 공간이 문제가 되거나 기술 문서의 특정 위치 또는 튜토리얼 단계와 스크린샷을 더 잘 맞추려면 스크린샷을 2개 이상 사용하십시오.
  * 인터페이스에서 이미 강조 표시되지 않은 이미지 요소를 설명할 때는 화살표와 콜아웃을 사용하십시오. 환경과 도구는 이미 분명하므로 이를 강조하기 위해 콜아웃을 사용하지 마십시오.
* 이미지는 `.mdx` 파일에 삽입하거나 가져오는(import) 두 가지 방법으로 넣을 수 있습니다. 특정 높이나 너비처럼 이미지에 스타일을 추가해야 할 때는 후자를 사용하십시오. 단, 이미지를 가져오면 파일 경로가 달라진다는 점에 유의하십시오.
* 이미지의 파일 경로는 이미지가 위치한 곳과 사용 방식(예: 삽입 vs. mdx 페이지로 가져오기 — 아래 예시 참고)에 따라 달라집니다.
* **예시(삽입)**: `![Deposit Flow Diagram](/public/img/op-stack/protocol/deposit-flow.png)`
* **예시(가져오기)**:

```jsx theme={null}
<Image
    src="/public/img/op-stack/protocol/deposit-flow.png"
    alt="Deposit Flow Diagram"
    width={400}
    height={400}
/>
```

* 문서 전체의 일관성을 유지하기 위해 아이콘은 [Remix](https://remixicon.com/)에서 가져옵니다. 다운로드하기 전에 Optimism Red `FF0420`으로 아이콘 색상을 지정하고, 아이콘은 `public/img/icons` 디렉터리에 저장하십시오.

### 동영상

* 동영상은 꼭 필요한 경우에만, 그리고 더 복잡한 작업에만 사용하십시오.
* 동영상과 애니메이션에는 의미 있는 대체 텍스트를 작성하십시오. 가능하면 캡션도 포함하십시오.
* 홍보 동영상은 가능한 한 짧아야 하며, 일반적으로 30초를 넘지 않아야 합니다.
* 애니메이션 GIF도 짧아야 하며, 일반적으로 10\~60초 사이여야 합니다.
* 튜토리얼 동영상은 교육 콘텐츠로 간주되며, 교수 설계 모범 사례에 따라 10분을 넘지 않아야 합니다.
* 튜토리얼 동영상은 서드파티(YouTube, Vimeo 등)에서 호스팅해야 하며, 접근성을 위해 자막(closed caption)을 포함해야 합니다.
* 동영상은 iframe으로 삽입하고, 필요에 따라 `title` 속성을 추가/수정하여 더 의미 있는 `alt-text`를 만드십시오. 이렇게 하면 스크린 리더의 접근성이 향상됩니다.
* **대체 텍스트용 title이 있는 동영상 예시:**

```html theme={null}
<iframe width="560" height="315" src="https://www.youtube.com/embed/_Y6CwsYgqwI?si=7erhCEj6cz1nD0VO"
title="Optimism Getting Started Tutorial" frameborder="0" allow="accelerometer; autoplay;
clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
```

## 링크

개발자는 우리가 읽고 있는 콘텐츠와 관련된 사이트나 페이지로 안내할 것이라고 신뢰합니다. 그 신뢰를 유지하려면 링크가 투명하고, 최신 상태이며, 신뢰할 수 있는 리소스로 연결되는 것이 중요합니다.

### 내부 링크

* 내부 링크는 H2 및 H3 제목 태그를 기준으로 자동 생성됩니다.

* 페이지의 특정 H2 또는 H3 섹션에 링크할 때 앵커 링크는 항상 소문자이며 공백 대신 대시가 사용됩니다.
  **예시**: `(H3) Test your application`은 앵커 링크로 `test-your-application`으로 변환됩니다.

* 가능하면 앵커 링크를 사용하여 사용자를 기술 문서의 특정 페이지와 위치로 안내하십시오. 이렇게 하면 인지 부하가 줄고 전반적인 사용성이 향상됩니다.

* 페이지 안의 H3 태그와 같은 앵커에 링크하려면 앞에 `#`을 붙여 페이지 이름 뒤에 추가해야 합니다. **예시**: `[any descriptive text](/app-developers/tutorials/tokens/deploy-superchain-erc20)`.

### 페이지 간 링크

* 사이트의 페이지 간에 링크할 때는 절대 링크 또는 상대 링크를 사용하십시오. 페이지가 중첩되어 있을 때 절대 링크가 더 깔끔하고 다루기 쉬우므로 절대 링크를 권장합니다.
  **예시**: 절대 링크 `(/op-stack/protocol/bridging/deposit-flow)` 대 상대 링크 `(../../protocol/deposit-flow)`

* 문장에서 페이지에 링크할 때는 가능하면 해당 페이지의 정확한 제목을 사용하되, 페이지 자체 제목이 아직 sentence case가 아니더라도 sentence case로 작성하십시오. 링크는 다른 서식(굵게, 기울임꼴, 따옴표) 없이 기본 스타일을 사용해야 합니다.
  **예시**: [The OP Stack](https://docs.optimism.io/op-stack/introduction/op-stack.md)을 확인하여 빠르게 익히십시오.

* 정확한 문서 제목을 사용하지 않고 문서에 링크할 때는 sentence case를 사용하십시오. 이렇게 하면 문장 흐름을 최소한으로 방해합니다. 링크는 기본 스타일을 사용해야 합니다.
  **예시**: 더 고급 내용을 원한다면 [L1과 L2 간에 데이터 보내기](https://docs.optimism.io/app-developers/bridging/messaging.md)에 관한 페이지를 읽어 보시기를 권장합니다.

* 현재 작업을 완료하는 데 중요한 자세한 지침이 담긴 다른 문서를 안내할 때는 `detailed instructions` 링크 형식을 사용하십시오.
  **예시**: 자세한 지침은 [Article Title](https://docs.optimism.io/app-developers/bridging/standard-bridge.md)을 참고하십시오.

* 현재 작업을 완료하는 데 필수는 아니지만 작업/주제와 관련되어 사용자에게 도움이 될 수 있는 추천 읽을거리로 안내할 때는 `more information` 링크 형식을 사용하십시오.
  **예시**: 자세한 내용은 [Article Title](https://docs.optimism.io/app-developers/bridging/standard-bridge.md)을 참고하십시오.

## 콘텐츠 유형

콘텐츠 유형은 각 파일 유형의 목적과 공통 구조를 정의하여 기술 콘텐츠를 관리하는 데 도움을 줍니다. 이 기술 문서에서 사용하는 모든 콘텐츠 유형에는 아래에 정의된 속성이 있습니다.

이 섹션에서는 각 콘텐츠 유형의 구조를 정의합니다. 각 콘텐츠 유형에 대해 어떤 소스가 정식(canonical)인지, 그리고 어떤 페이지가 docs.optimism.io에 속하는지 여부는 [콘텐츠 가이드](https://docs.optimism.io/ko/op-stack/contribute/content-guide.md)를 참고하십시오.

| 문서 유형 | 목적 | 예시 |
| - | - | - |
| 개요 또는 설명서 | 제품이나 기능에 대한 일반적인 소개를 제공하고 독자를 위한 happy path를 제시 | [Superchain 설명서](https://docs.optimism.io/superchain/superchain-explainer.md) |
| 가이드 | 무엇이 무엇인지, 어떻게 작동하는지 설명 | [Standard Bridge 가이드](https://docs.optimism.io/app-developers/bridging/standard-bridge.md) |
| 튜토리얼 | 단계별 "직접 해 보며 배우기" 지침으로 작업 중심의 안내를 제공 | [viem으로 ERC-20 토큰 브리징하기](https://docs.optimism.io/app-developers/tutorials/bridging/cross-dom-bridge-erc20.md) |
| FAQ | 자주 묻는 질문에 답변 | [FAQ: OP Mainnet 보안 모델](https://docs.optimism.io/op-stack/security/faq-sec-model.md) |
| 문제 해결 | 일반적인 문제 해결 시나리오와 해결 방법을 나열 | [문제 해결: 노드 실행](https://docs.optimism.io/operators/node-operators/management/troubleshooting.md) |
| 레퍼런스 | API 엔드포인트 및 사양처럼 시스템 내부 작동에 대한 깊이 있는 이론적 지식을 제공 | [노드 및 RPC 제공업체](https://docs.optimism.io/app-developers/tools/connect/rpc-providers.md) |

### 개요(또는 설명서)

개요 또는 설명서는 제품이나 서비스에 대한 일반적인 소개를 제공하고, 독자가 특정 문서 집합이나 관련 기능을 탐색하는 happy path를 제시합니다. 잘 작성된 개요와 설명서는 사용자를 위해 다음 두 가지 핵심 작업을 수행합니다.

1. 관련 문서 페이지들을 **구성**하여 개발자가 너무 많은 정보에 압도되지 않도록 합니다.
2. 사용자 시나리오나 사용 사례에 따라 개발자를 문서 집합의 적절한 페이지로 안내하는 **'happy path'를 수립**합니다.

표는 개요 페이지에 매우 효과적이며, 페이지 콘텐츠를 구성하는 동시에 특정 개발자 사용 사례에 대한 happy path를 수립할 수 있습니다. 또는 사용 사례, 사용자 시나리오 또는 디렉터리 페이지 제목별로 구성된 헤딩(H2)을 사용할 수도 있습니다.

일관성을 유지하기 위해 개요에는 다음 항목이 모두 포함되어야 합니다.

* 페이지에서 다룰 내용에 대한 개요
* 사용 사례, 사용자 시나리오 또는 페이지 제목별로 개별 섹션으로 구성된 콘텐츠
* 병렬 구조로 작성된 각 섹션의 명확한 헤딩
* 다음 단계 섹션: 관련 가이드, 튜토리얼 등에 대한 링크

### 가이드

가이드는 무엇이 무엇인지, 어떻게 작동하는지와 같은 개념이나 복잡한 기능을 간단한 언어로 설명합니다. 초급 개발자의 온보딩에 매우 적합합니다. 개발자 중심 가이드에서는 개념 설명에 도움이 되도록 가능한 한 일러스트, 다이어그램, 코드 샘플을 포함하는 것이 모범 사례입니다.

일관성을 유지하기 위해 가이드에는 다음 항목이 모두 포함되어야 합니다.

* 가이드에서 다룰 내용에 대한 개요
* 개별 섹션으로 구성된 가이드 콘텐츠
* 병렬 구조로 작성된 각 섹션의 명확한 헤딩
* 하나 이상의 시각적 요소(예: 이미지, 스크린샷, 일러스트 및/또는 코드 샘플)
* 다음 단계 섹션: 관련 튜토리얼, 다른 가이드, 문제 해결 등에 대한 링크

### 튜토리얼

튜토리얼은 작업, 활동 또는 목표를 완료하기 위한 실용적인 단계별 지침이 포함된 작업 중심의 페이지 또는 동영상입니다. 튜토리얼은 다른 기술 문서보다 더 상호작용적이고 실습 중심이며, 개발자가 직접 해 보며 배울 수 있도록 실용적인 예제, 연습, 시연을 포함하는 경우가 많습니다.

일관성을 유지하기 위해 튜토리얼에는 다음 항목이 모두 포함되어야 합니다.

* 해결하려는 문제에 대한 맥락을 포함하여 튜토리얼에서 다룰 내용에 대한 개요
* 튜토리얼의 목표(즉, 개발자가 배우게 될 내용 또는 완료 상태)
* 시작하기 전에 섹션(사전 요구 사항이라고도 함)
* 작업에 포함된 단계 목록
* 이미지, 스크린샷 또는 코드 샘플(이상적으로는 각 단계마다 이 중 하나 이상)
* 다음 단계 섹션: 다른 튜토리얼, 관련 가이드, 문제 해결 등에 대한 링크

튜토리얼이나 빠른 시작 문서를 작성할 때 단계는 동명사("ing"로 끝나는 형태)가 아닌 명령형 동사를 사용한 문장으로, 병렬 구조로 작성해야 합니다.

> **예시:**
>
> * 1단계: 사이트 **만들기**
> * 2단계: 프레임워크 **선택하기**
> * 3단계: 개발 환경 **방문하기**

### FAQ

FAQ는 가독성이 떨어지고 유지 관리가 어렵기 때문에 가능하면 사용하지 않아야 합니다.

FAQ는 제품, 기능 또는 서비스에 대해 개발자가 가지고 있거나 물어볼 수 있는 일반적인 질문에 답합니다. FAQ는 개발자의 관점에서 작성해야 합니다. 답변에 두 단계 이상이 있으면 번호 목록을 사용하십시오. 가능하면 FAQ는 별도의 페이지에 배치하고, 해당 가이드나 튜토리얼 안에서 FAQ로 링크하십시오.

일관성을 유지하기 위해 FAQ에는 다음 항목이 모두 포함되어야 합니다.

* FAQ가 다루는 제품 또는 서비스에 대한 개요
* 질문(페이지에 따라 보통 H2 또는 H3)
* 답변(헤딩이 아니며, 보통 질문 아래의 일반 단락 텍스트)

FAQ의 헤딩 수준은 FAQ 전용 문서인지, 더 큰 문서의 일부로 FAQ가 포함된 것인지에 따라 달라집니다. 어느 경우든 문서를 구성할 때 H3 수준을 넘지 않도록 하십시오.

**간단한 FAQ 예시**

> **Optimism은 ERC-721을 지원합니까?**
> 예. ERC-721 표준을 완전하게 지원합니다.

**지침형 FAQ 예시**

> **Optimism 비밀번호는 어떻게 변경합니까?**
>
> 1. 사용자 계정 드롭다운 메뉴에서 **Sites & Accounts**를 선택합니다.
> 2. **Account** 탭을 클릭합니다.
> 3. **Change Password**를 선택합니다.
> 4. 정보를 입력하고 **Save**를 클릭합니다.

관련 FAQ 콘텐츠를 묶어야 할 때는 카테고리 헤딩을 포함하십시오. 카테고리 헤딩은 선택 사항이지만, 긴 FAQ에서는 유용합니다.

### 문제 해결 가이드

문제 해결 가이드는 개발자가 제품이나 서비스를 사용하면서 겪을 수 있는 일반적인 문제를 나열하고, 증상을 식별하며, 해결 방법을 제시합니다. 개발자가 자신의 시스템 반응이 문제 해결 가이드에서 식별한 일반적인 문제 중 하나와 일치하는지 알 수 있도록 시스템이나 인터페이스가 나타내는 증상(예: 오류 메시지, 예기치 않은 페이지 새로 고침/다시 로드, 회전하는 로딩 아이콘 등)을 정확하게 기록하는 것이 중요합니다.

문제 해결 가이드는 하나의 특정 제품이나 서비스에 대한 일반적인 문제를 식별하는 것으로 범위를 제한해야 합니다.

일관성을 유지하기 위해 문제 해결 가이드에는 다음 항목이 모두 포함되어야 합니다.

* 문제 해결 가이드가 다룰 제품 또는 서비스에 대한 개요
* 일반적인 문제(페이지에 따라 보통 H2 또는 H3)
  * 문제의 원인
  * 문제의 증상(이미지/스크린샷으로 기록한 시스템 반응)
* 해결 방법(단계별)
* 다음 단계 섹션: 관련 튜토리얼, 다른 가이드 등에 대한 링크

### 기술 레퍼런스

기술 레퍼런스는 시스템 내부 작동에 대한 깊이 있는 이론적 지식을 제공합니다. 이는 개발자가 제품을 효율적으로 실행하는 데 필요한 요구 사항이나 시스템 사양의 형태로 제공되는 경우가 많으므로, API 엔드포인트와 오류 코드 같은 목록과 표가 흔히 사용됩니다.
기술 레퍼런스 페이지는 보통 상당히 길기 때문에 개발자를 위해 자료를 정리할 수 있도록 페이지 상단에 목차(TOC)를 삽입하는 것이 모범 사례입니다. 사용성 관점에서 이 방식은 레퍼런스에서 다룰 내용을 개발자에게 미리 보여 주고, 원하는 경우 특정 섹션으로 바로 이동할 수 있게 해 줍니다.

일관성을 유지하기 위해 기술 레퍼런스에는 다음 항목이 모두 포함되어야 합니다.

* 레퍼런스에서 다룰 내용에 대한 개요
* 목차
* 병렬 구조의 헤딩과 함께 개별 섹션으로 구성된 레퍼런스 콘텐츠
* 하나 이상의 시각적 요소(예: 흐름도, 일러스트 및/또는 코드 샘플)
* 추가 읽을거리 제안(레퍼런스 문서 곳곳에 분산된 링크)

기술 레퍼런스는 다른 콘텐츠 유형보다 문서 전체에 더 많은 링크를 포함하는 경우가 많으며, 다른 기술 레퍼런스, 가이드, 튜토리얼, 용어집 정의 등으로 링크하는 경우가 많습니다. 기술 레퍼런스 자료의 목적은 개발자가 선택한 주제에 대해 더 깊은 수준으로 교육하는 것이므로, 이는 일반적이고 예상되는 관행이며 훌륭한 기술 레퍼런스라는 좋은 신호입니다.

## 일반 서식

### 글꼴

Optimism 기술 문서의 글꼴은 마케팅 팀이 수립한 브랜드 가이드라인을 따르도록 설정되어 있습니다(예: 헤딩 글꼴은 본문 또는 단락 글꼴과 다릅니다). 글꼴을 변경하지 마십시오.

### 글머리 기호 및 순서 없는 목록

목록 항목에는 `-` 대신 `*`를 사용하십시오. 이렇게 하면 문서 전체의 일관성이 유지됩니다.

### 날짜 및 숫자

* 가능하면 날짜에 월, 일, 연도 전체 형식을 사용하십시오. 월을 축약하지 마십시오. 양식이나 공간이 제한된 곳에서는 앞에 0을 붙이지 않고 월/일/연도 형식으로 슬래시를 사용하십시오.
  **예시**: `January 10, 2014` 또는 `2024/01/10`

* 10 미만의 숫자는 모두 단어로 표기하십시오. 10 이상의 숫자는 숫자로 표기하십시오.
  **예시**: CompanyX operates five nodes and plans to add 12 more.

### 축약

* 축약형은 의도적으로 사용하십시오. 축약형은 FAQ나 튜토리얼처럼 대화체의 비격식적인 어조를 만드는 데 사용할 수 있습니다. UI 레이블(예: 버튼 이름, 페이지 헤더 등), 오류 메시지/오류 코드 또는 상호작용 페이지 요소에서는 축약형을 사용하지 마십시오.

* 일반적인 단어를 축약하지 마십시오. 표처럼 공간 제약이 큰 경우가 아니라면 전체 단어로 쓰는 것이 좋습니다.
  **예시**: `Use account`(acct. 아님) 및 `number`(no. 아님)

* 각 페이지에서 약어를 처음 사용할 때는 전체 단어로 표기하십시오. 그 뒤 괄호 안에 약어를 표기합니다. 해당되는 경우 사용자를 용어집으로 연결하십시오.
  **예시**: `Externally Owned Account (EOA)`

### 문장 부호

* **앰퍼샌드(&)** 항목을 묶는 헤딩이나 고유 명사에서만 "&"를 사용하십시오. 문장 안에서는 사용하지 마십시오.

* **콜론(:)** 목록이나 연속된 항목을 소개할 때 사용하십시오.

* **쉼표(,)** 세 개 이상의 항목을 나열할 때는 연속 쉼표(serial comma)를 사용하고, 목록의 마지막 요소 앞 "and" 앞에 옥스퍼드 쉼표를 사용하십시오.
  **예시**: The developer built a node, social app, and DeFi app for Optimism.

* **엠 대시(—)** 생각의 단절이나 삽입 설명을 나타낼 때 사용하십시오. 엠 대시 앞뒤에 공백을 넣지 마십시오.
  **예시**: The developer graduated—with honors—from Optimism Bootcamp.

* **엔 대시(–)** 범위나 연속을 나타낼 때 사용하십시오. 엔 대시 양쪽에 공백을 넣으십시오.
  **예시**: `Pages 11 – 19` 또는 `Mon – Fri` 또는 `Nov 1 – 17`

* **느낌표(!)** 사용하지 마십시오. 사용자 지원 콘텐츠에서는 느낌표를 사용하지 않습니다. 느낌표는 마케팅 및 영업 콘텐츠에는 적합하지만 UI나 기술 문서에는 적합하지 않습니다.

* **하이픈(-)** 두 단어를 연결할 때 사용하십시오. 하이픈 앞뒤에는 공백이 필요하지 않습니다.
  **예시**: `developer-focused product` 또는 `company-wide holiday`

* **슬래시(/)** 슬래시는 파일 이름용으로 예약되어 있으므로(위 참고) 사용하지 마십시오. 대신 "또는", "그리고", "둘 다"를 사용하십시오.