Text Formatting Guide

출처: 문서

본문

텍스트 서식 가이드

이 가이드는 OpenSearch 문서에서 코드 예제, 목록, 링크, 이미지, 절차 등 콘텐츠 요소를 서식 지정하고 구성하는 규칙을 제공합니다. 브랜드 아이덴티티, 명명 규칙, 어조와 톤에 대해서는 스타일 가이드를 참조하세요. 문법, 구두점, 단어 선택에 대해서는 작성 가이드를 참조하세요. Markdown 및 Jekyll 구문에 대해서는 마크다운 서식 가이드를 참조하세요.

코드 예제

문장이나 코드 블록 안에서 코드를 표시하면 독자에게 어떤 항목이 코드에 해당하는지 명확해집니다. 다음은 코드 예제 사용 및 code font를 사용해야 하는 경우에 대한 일반적인 지침입니다.

• Markdown에서는 인라인 코드 서식에 백틱 하나(`)를 사용하고, 코드 블록에는 백틱 세 개를 사용합니다. (```) for code blocks. For example, writing `discovery.type` in Markdown will render as discovery.type. A line containing three backticks should be included both before and after an example code block.
• In sentences, use code font for things relating to code, for example, "The from and size parameters are stateless, so the results are based on the latest available data."
• Use lead-in sentences to clarify the example. Exception: API examples, for which a caption-style lead-in (heading 4) is sufficient.
• Use the phrase such as for brief examples within a sentence.
• Use language-specific indentation in code examples.
• Use example, not sample, to introduce example blocks (for example, code, scripts, and API requests and responses).
• Make code blocks as copy-and-paste friendly as possible. Use either the copy or copy-curl buttons.

Code formatting checklist

The following items should be in code font:

• Field names, variables (including environment variables), and settings (discovery.type, @timestamp, PATH). Use code font for variable and setting values if it improves readability (false, 1h, 5). Plain text is also acceptable for simple numeric values, such as 5.
• Placeholder variables:
  • Use angle brackets in command-line examples (docker exec -it <container-id> /bin/bash).
  • Use curly braces in API paths (GET /{index}/_search, PUT /_snapshot/{repository}/{snapshot}).
• Commands, command-line utilities, and options (docker container ls -a, curl, -v).
• File names, file paths, and directory names (docker-compose.yml, /var/www/simplesamlphp/config/).
• URLs and URL components (localhost, http://localhost:5601).
• Index names (logs-000001, .opendistro-ism-config), endpoints (_cluster/settings), and query parameters (timeout).
• Language keywords (if, for, SELECT, AND, FROM).
• Operators and symbols (/, <, *).
• Regular expression, date, or other patterns (^.*-\d+$, yyyy-MM-dd).
• Class names (SettingsModule) and interface names (RestHandler). Use italics for interface names.
• Text field inputs (Enter the password admin).
• Email addresses ([email protected]).

Do not start a sentence with a word in backticks. Restructure to avoid leading with inline code: "The validate_action parameter controls..." (not "validate_action controls...").

Caption-style examples

If you use a caption-style example, use a heading with "Example" followed by a colon. The following are caption-style examples:

Example: Retrieve a specified document from an index

The following example request retrieves a specific document from an index:

GET sample-index1/_doc/1

Example request

GET sample-index1/_doc/1

Sometimes, you might not want to break up the flow of the text with a new heading. In these cases, you can use an example with no heading:

The following command maps ports 9200 and 9600, sets the discovery type to single-node, and requests the newest image of OpenSearch:

docker run -d -p 9200:9200 -p 9600:9600 -e "discovery.type=single-node" opensearchproject/opensearch:latest

Lead-in sentences

When using lead-in sentences, summarize, clarify, or refer to the example that follows. A lead-in sentence is a complete sentence that ends in a colon, as shown in the following example.

For example, the following query requests statistics for docs and search:

GET _nodes/stats/indices/docs,search

Referring to a variable or placeholder

When introducing a code or command line example that refers to a variable or placeholder in the example, be direct by including the variable or placeholder name in the text. Surround the variable or placeholder name with angle brackets (< and >), for example, <port>. Don't refer to the variable or placeholder by its color or format because these can change. If variable or placeholder texts have a lot in common and there are several for the user to complete, be direct by including a "template" for the input in the replaceable text.

In the following example, replace <component-x> with your own information:

~/workspace/project-name$ eb init --modules <component-a> <component-b>

서식 및 구성

• 모든 UI 요소(페이지, 창, 대화 상자 등)에는 굵은 텍스트를 사용하세요. 모든 경우에 UI 요소 자체에 대해 말하기보다 사용자가 수행해야 할 작업을 강조하세요. 굵은 서식 안에 구두점을 포함하지 마세요. 예: 관리: (**관리:**가 아님).

• 중첩된 제목은 콘텐츠에 절대 나타나지 않아야 합니다. 중첩된 제목은 텍스트 없이 연속으로 나오는 두 개의 제목입니다. 소개 문장이 있더라도 모든 제목 아래에는 항상 텍스트가 있어야 합니다.

• 용어를 처음 사용할 때는 이탤릭체로 정의하세요. 예: "분산(distributed)이라는 용어는 OpenSearch를 여러 컴퓨터에서 실행할 수 있음을 의미합니다."

• API를 참조하는 방법은 세 가지입니다.

  1. API 이름을 참조할 때는 이름의 모든 단어를 대문자로 표기합니다(예: "Field Capabilities API").
  2. 엔드포인트의 정확한 이름으로 API 작업을 참조할 때는 소문자와 코드 서식을 사용합니다(예: "_field_caps API").
  3. API 작업을 설명하지만 엔드포인트의 정확한 이름을 사용하지 않을 때는 소문자를 사용합니다(예: "field capabilities API operations" 또는 "field capabilities operations").

이미지

• 각 이미지에 충분한 맥락을 제공하는 소개 텍스트를 추가하세요.

• 스크린 리더를 위해 이미지를 설명하는 대체 텍스트(ALT)를 추가하세요.

• 이미지의 위치를 설명할 때는 _above_와 below 대신 preceding, previous, _following_과 같은 단어를 사용하세요.

• 코드와 목록의 도입 문장(콜론으로 끝남)과 달리 이미지를 소개하는 텍스트는 완전한 문장이어야 하며 마침표로 끝나야 합니다.

스크린샷

스크린샷은 UI가 변경될 때마다 구식이 되므로 유지 관리가 어렵습니다. 스크린샷 포함 여부를 결정할 때는 자신의 판단을 사용하세요. UI가 자명하거나 자주 변경될 가능성이 있는 경우 UI 요소를 굵게 표시한 단계별 절차로 충분합니다.

스크린샷을 포함할 때는 모든 텍스트를 확대하지 않고도 읽을 수 있어야 합니다. 사용자가 이미지에서 레이블, 필드 이름 또는 값을 읽을 수 없는 경우 브라우저 창 크기를 조정하거나 캡처하기 전에 관련 요소 주위를 꼭 맞게 자르세요.

스크린샷에 주석을 달 때는 콜아웃에 상자를 사용하고 번호가 매겨진 주석에는 빨간 원 배경에 흰색 숫자를 사용하세요. 스크린샷에 레이블이 지정된 콜아웃이 있는 경우 이미지 아래 목록에서 레이블이 없는 구성 요소는 이탤릭체 이름을, 레이블이 지정된 UI 요소는 굵은 텍스트를 사용하고 해당 콜아웃 문자를 괄호 안에 넣어 설명하세요. 이 목록에는 도입 문장이 필요하지 않습니다. 예:

• 시간 필터(C)는 데이터 범위를 선택하기 위한 그래픽 인터페이스를 제공합니다.
• 결과 테이블(H)은 선택한 문서의 요약을 표시합니다.

콜아웃이 숫자인 경우 대신 번호 매기기 목록을 사용하세요:

1. 쿼리 표시줄(1)은 DQL 또는 Lucene 구문의 검색 쿼리를 허용합니다.
2. 시간 필터(2)는 결과를 지정된 날짜 범위로 제한합니다.

링크

• 공식 상호 참조: 대부분의 경우 공식 상호 참조(링크하는 페이지의 제목)가 선호되는 스타일입니다. 맥락을 제공하고 독자가 링크를 선택할 때 어디로 이동하는지 이해하는 데 도움이 되기 때문입니다. 공식 상호 참조에 대한 다음 지침을 따르세요:

  • 링크를 공식적인 도입 텍스트로 소개하세요:

    • "For information about" 또는 "For more information about"를 사용하세요. "For information on"은 사용하지 마세요.
    • 절차에 링크하는 경우 "For instructions on" 또는 "instructions for"를 사용할 수 있습니다. "instructions about"은 사용하지 마세요.
    • 공간이 제한된 경우(예: 표) "See [링크 텍스트]"를 사용할 수 있습니다.

  • 링크 텍스트가 섹션 제목 텍스트와 일치하는지 확인하세요.

    "참여하려면 OpenSearch 웹사이트의 기여하기를 참조하세요."

• 임베디드 링크: 임베디드 링크는 공식적인 도입 텍스트 없이 문장에 포함됩니다. 공간이 좁은 표나 다른 요소에서 특히 유용합니다. 임베디드 링크 주변의 텍스트는 링크의 정보와 관련되어야 독자가 맥락을 이해할 수 있습니다. 접근성 문제를 일으키므로 링크 텍스트로 here 또는 _click here_를 사용하지 마세요.

  "마지막으로, 인덱스를 삭제하세요."

목록

다음 지침은 모든 목록 유형에 적용됩니다:

• 목록은 내용과 구조가 병행되도록 만드세요. 단일 단어와 구문을 혼합하지 말고, 일부 구문을 명사로 시작하고 다른 구문을 동사로 시작하지 말며, 동사 형태를 혼합하지 마세요.
• 항목의 순서가 임의적인 경우 항목을 알파벳 순서로 표시하세요.
• 각 목록 항목의 첫 단어 첫 글자는 대문자로 표기하세요.
• 목록이 간단한 경우 목록 항목에 끝 구두점이 필요하지 않습니다.
• 목록에 구문과 문장이 혼합된 경우 각 목록 항목에 구두점을 찍으세요.
• 목록 항목에 둘 이상의 문장이 있는 경우 각 목록 항목을 마침표로 끝내세요.
• 목록 항목의 구두점을 일관되게 사용하세요. 목록에서 하나 이상의 항목에 마침표가 필요한 경우 해당 목록의 모든 항목에 마침표를 사용하세요.
• 목록에는 도입 문장이 필요합니다.
• 도입 문장은 완전한 문장이어야 합니다.
• 도입 문장은 콜론으로 끝나야 합니다.
• 목록 항목 끝에 세미콜론, 쉼표 또는 접속사(예: and 또는 or)를 사용하지 마세요.

절차

절차는 사용자가 특정 작업을 완료하기 위해 따르는 일련의 번호가 매겨진 단계입니다. 사용자가 절차를 쉽게 찾고 인식할 수 있어야 합니다. 다음을 사용하여 절차를 인식 가능하게 만드세요:

• 예측 가능한 콘텐츠 부분
• 병행 언어 구조
• 일관된 서식

UI와의 상호 작용 설명

포인터 관련 동작을 장치에 구애받지 않는 일반 동사로 대체하여 장애가 있는 독자와 포인터, 키보드, 터치 스크린 등 다양한 입력 방법 및 장치 사용자를 수용하세요. click 또는 _swipe_와 같은 장치별 동사를 사용하지 마세요. 그러나 일반적인 언어로 지침을 이해하기 어려운 경우 괄호 안에 포인터 관련 힌트를 포함할 수 있습니다. 판단을 사용하세요. 질문이 있으면 편집자에게 문의하세요.

다음 표와 같이 UI와의 상호 작용 설명에 대한 Microsoft Writing Style Guide 지침을 약간 수정한 버전을 따릅니다.

더 알아보기 (Learn more)

• 원문 전체: https://docs.opensearch.org/latest/style-guide/TEXT_FORMATTING_GUIDE/