스타일 가이드

이 가이드에 따라 GitHub의 설명서가 독자가 이해할 수 있도록 일관성을 유지하고 명확한 패턴을 따르도록 합니다.

이 문서의 내용

Note

이 가이드는 GitHub의 설명서에만 해당됩니다. 여기서 다루지 않는 주제에 대한 일반적인 스타일 관련 질문 또는 지침은 Microsoft 스타일 가이드를 참조하세요. docs.github.com의 소스 콘텐츠와 관련된 변경 내용은 GitHub Docs에서 Markdown 및 Liquid 사용하는 방법을(를) 참조하세요. GitHub 브랜드에 관한 질문은 GitHub 브랜드 가이드를 참조하세요.

스타일에 대한 GitHub Docs 접근 방식

  • 이 스타일 가이드는 간결함을 지향합니다. 지침을 다양한 시나리오에 쉽게 적용할 수 있어야 합니다.
  • 문법 또는 스타일 가이드의 규칙에 따라 무엇이 옳고 그른지를 결정하는 것이 아니라 사용자에게 가장 적합한 것을 결정합니다. 일관성을 유지하는 동시에 변화에 유연하고 개방적이게 대응합니다.
  • 팀과 설명서 규모의 성장에 맞춰 스타일 가이드를 조정하고 사용자에게 고품질의 의미 있는 콘텐츠를 제공하기 위해, 모든 스타일 질문을 포괄적으로 다루기보다는 영향력과 가치가 큰 시나리오에 집중합니다.
  • 일관성과 문법적 정확성도 중요하지만 명확성과 의미를 더 중요하게 다룹니다.
  • 스타일 또는 구조에 대한 결정을 내릴 때 콘텐츠 단위 내의 정보 흐름과 정보의 맥락을 고려합니다.
  • 도움말 설명서와 관련된 질문을 스타일 가이드에서 다루지 않는 경우 위와 같은 원칙을 고려해 결정합니다. 이와 관련한 궁금증이 있다면 우리는 해당 결정에 대해 논의 할 준비가 되어있습니다.

감사 로그 이벤트

각 계정 유형(사용자, 조직 및 엔터프라이즈)의 감사 로그에 나타날 수 있는 모든 이벤트를 문서화합니다.

감사 로그 이벤트에 대한 설명을 작성할 때는 과거 시제와 수동태를 사용하여 모든 버전에 적용되도록 발생한 이벤트를 설명합니다. "~을 트리거로 사용하는"과 같이 문서의 컨텍스트에 이미 나타난 문구로 문장을 시작하지 마세요.

  • 올바른 사용: 리포지토리 시각화가 변경되었다.
  • 올바른 사용: 모든 새 리포지토리에서 비밀 검사를 사용할 수 있습니다.
  • 잘못된 사용: 조직 소유자가 조직에 대한 2단계 인증 요구 사항을 사용하지 않도록 설정했습니다.
  • 잘못된 사용: 코드스페이스에서 접근할 수 있는 리포지토리를 사용자가 업데이트할 때 트리거됩니다.

경고

경고는 문서 내에서 특별히 중요한 정보를 강조하고 정보의 흐름을 끊는 것을 정당화합니다.

경고는 가급적 사용하지 마십시오. 연속 경고 또는 섹션당 둘 이상의 경고는 사용하지 마십시오.

경고는 간결해야 합니다. 정보가 두 개 이상의 문장으로 구성되거나 순서가 지정되거나 순서가 지정되지 않은 목록이 필요한 경우 대신 섹션 제목 아래에 정보를 배치하는 것이 좋습니다.

경고 유형

Note, Tip, Warning 및 Caution의 네 가지 유형의 경고를 사용합니다.

참고 항목

사용자가 고려해야 할 수 있는 추가 컨텍스트를 제공합니다. 메모 경고의 정보 없이 작업을 수행할 수 있지만 일부 컨텍스트에서 일부 사용자에게 메모는 도움이 될 수 있습니다.

참고는 설명되는 프로세스의 중심이 아닌 괄호 정보를 전달하는 데 특히 유용합니다.

  • 특정 사용자 설정과 같이 프로세스의 결과에 영향을 줄 수 있는 주의 사항입니다.
  • 베타 또는 사용되지 않음의 제품 및 기능과 같이 가용성이 변경될 수 있습니다.

예를 들어 비밀 검사에서 경고 평가은(는) 메모를 사용하여 GitHub 토큰의 메타데이터가 현재 베타에 있음을 사용자에게 알립니다.

Note

GitHub 토큰에 대한 메타데이터는 현재 베타 버전이며 변경될 수 있습니다.

팁

권장 사항, 모범 사례 또는 제품 힌트입니다. 팁에는 사용자가 재량에 따라 따를 수 있는 필수적이지 않은 정보가 포함되어 있습니다. 특히 새 사용자를 대상으로 하는 문서에서 유용합니다.

예를 들어 프로필 개인 설정은(는) 팁 경고로 사용자가 조직을 @mention할 때 예상할 수 있는 것을 이해하는 데 도움이 됩니다.

Tip

조직을 @mention할 경우 구성원인 사용자만 자동으로 완성됩니다. 이전 고용주처럼 구성원이 아닌 조직을 여전히 @mention할 수 있지만 조직 이름은 자동으로 완성되지 않습니다.

Warning

작업을 시작하거나 계속하기 전에 사용자가 알아야 할 잠재적 위험을 강조 표시합니다.

Warning 경고는 명령줄 또는 API를 통해와 같이 GitHub UI 외부에서 발생하는 프로세스와 특히 관련이 있습니다.

예를 들어 SSH 인증 기관 정보에는 명령줄에 대한 지침이 포함되어 있으며 경고를 사용하여 발급된 후에는 인증서를 해지할 수 없음을 사용자에게 알립니다.

Warning

인증서가 서명되고 발급된 후에는 인증서를 해지할 수 없습니다. -V 플래그를 사용하여 인증서의 수명을 구성해야 합니다. 그렇지 않으면 인증서를 무기한 사용할 수 있습니다.

주의

특히 보안 위험 또는 데이터 손실 가능성이 있는 경우 수행하기 전에 극도의 주의를 기울여야 하는 위험하거나 파괴적인 작업을 사용자에게 경고합니다.

Caution 경고는 일반적으로 명령줄 또는 API를 통해와 같이 GitHub UI 외부에서 발생하는 프로세스를 설명할 때만 필요합니다.

경고 서식 지정

설명서 집합에 있는 다양한 유형의 경고에 표준 서식 및 색상을 사용합니다.

경고는 Markdown을 사용하여 렌더링됩니다.

고:

> [!NOTE]
> Keep this in mind.

팁:

> [!TIP]
> Here's a suggestion.

경고:

> [!WARNING]
> Be careful.

주의:

> [!CAUTION]
> Be extremely careful.

경고에 대한 Liquid 구문은 여전히 지원되며 이전 문서에 계속 나타날 수 있지만 새 경고에 사용하면 안 됩니다.

경고 서식 지정에 대한 자세한 내용은 GitHub Docs에서 Markdown 및 Liquid 사용하는 방법의 “경고”를 참조하세요.

버튼

방문 페이지 및 일부 문서에는 사용자가 다른 문서 또는 다른 GitHub 웹 페이지의 관련 콘텐츠로 이동할 수 있는 단추가 있습니다. 설명된 작업을 완료하기 위해 다른 페이지로 이동해야 하는 경우에 단추를 사용합니다. 예를 들어 GitHub Enterprise Cloud 평가판 설치에는 평가판 설정 프로세스의 다음 단계인 평가판 등록 페이지로 사용자를 이동시키는 단추가 있습니다. 마이그레이션 설명서 방문 페이지는 단추를 사용하여 대부분의 사람이 마이그레이션을 시작하기 위해 읽어야 하는 문서로 사용자를 안내합니다.

단추가 GitHub Docs 사이트에서 벗어나도록 권장하는 경우 CTA (행동 유도) 단추 지침을 따릅니다. 방문 페이지나 문서에 있는 다른 유형의 버튼을 포함하고자 하는 경우, GitHub Docs 팀의 승인을 받아야 합니다.

CTA (행동 유도) 단추

CTA 단추는 문서를 읽은 후 또는 문서에서 설명하는 작업을 완료하는 과정의 일부로 사용자가 탐색하도록 권장하거나 예상하는 링크를 강조합니다. CTA는 GitHub에서 소유한 도메인으로만 사용자를 보내야 합니다. 예를 들어 GitHub Copilot을 사용하여 IDE에서 코드 제안 가져오기의 “GitHub Copilot 사용해 보기” CTA는 GitHub.com의 GitHub Copilot 설정 메뉴로 연결합니다.

해당 링크로 이동하는 것이 사용자의 요구 사항에 도움이 되는 경우에만 CTA 단추를 포함합니다. GitHub 기능 또는 제품을 홍보할 목적으로만 CTA 단추를 사용하지 마세요. 위의 예제에서 GitHub Copilot을(를) 시도하려는 사람은 Copilot 설정 메뉴로 이동해야 하며 문서를 읽은 후 이동하기를 원할 수 있습니다. 반면 누군가는 Copilot를 코드 작성의 일부로 사용해서 이에 대한 끌어오기 요청을 생성할 수도 있지만 Copilot가 “끌어오기 요청 만들기”의 사용자 요구와 관련이 없기 때문에 “GitHub Copilot 시도하기” CTA를 끌어오기 요청 만들기에 추가하지 않습니다. 대부분의 사용자는 Copilot을(를) 사용하지 않고 끌어오기 요청을 만듭니다. 그러나 Copilot을(를) 시작하는 방법에 대한 문서를 방문하는 이들은 이미 사용 중이 아니라면 Copilot을(를) 시도하는 데 관심이 있을 것입니다. 따라서 CTA 단추를 추가하여 방문자가 이동하려는 곳으로 갈 수 있도록 합니다.

다음 형식을 사용하여 CTA의 스타일을 지정합니다.

<a href="https://github.com/DESTINATION/URL?ref_cta=CTA+NAME&ref_loc=LOCATION&ref_page=docs" target="_blank" class="btn btn-primary mt-3 mr-3 no-underline"><span>Try PRODUCT NAME</span> {% octicon "link-external" height:16 %}</a>

자리 표시자를 CTA와 관련된 정보로 바꿉니다.

  • DESTINATION/URL: 단추가 이동해야 하는 URL입니다.
  • CTA+NAME: CTA의 이름입니다. 예를 들어 GHEC+trial 또는 Copilot+Business+Trial입니다.
  • LOCATION: CTA GitHub Docs의 위치입니다. 예들 들어 Setting+up+a+trial+of+GitHub+Enterprise+Cloud입니다.

코드

코드 블록

코드 블록에서 사용자가 가로로 스크롤할 필요가 없도록 코드 샘플의 줄을 약 60자로 유지합니다. 코드 블록 내에서 주석을 사용하는 대신 코드 블록 앞에 설명 텍스트를 적습니다. 코드 블록의 구문과 서식에 대한 자세한 내용은 GitHub Docs에서 Markdown 및 Liquid 사용하는 방법을(를) 참조하세요.

코드 블록 안에서:

  • 첫 번째 코드 펜스 뒤에 샘플 언어를 명시합니다. 지원되는 모든 언어 목록은 github/docs 리포지토리의 코드 언어를 참조하세요.

  • HTML을 사용하여 코드 블록의 스타일을 지정하거나 마크업을 지정하지 마세요.

  • 사용자가 고유값으로 바꾸어야 하는 자리 표시자의 스타일을 모두 대문자로 지정합니다.

    • 올바른 사용: git checkout -b BRANCH-NAME
    • 잘못된 사용: git checkout -b <branch-name>

  • $과(와) 같은 명령 프롬프트를 명령 자체 앞에 사용하지 마세요. 이러한 프롬프트는 독자가 명령을 복사하여 붙여넣는 것을 어렵게 만듭니다.

    • 명령과 명령의 출력을 표시하는 경우 예시의 출력을 주석으로 처리하세요.

    • 올바른 사용:

      command
# output

    • 잘못된 사용:

      $ command
output

  • 코드 예제에 { 또는 }를 표시해야 하는 경우에는 해당 섹션을 {% raw %} {% endraw %}로 래핑해서 Liquid 처리를 비활성화한다.

    • 사용:

      GITHUB_TOKEN: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}

    • 잘못된 사용:

      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  • 코드 예제에 구문 분석해야 하는 콘텐츠가 포함된 경우 해당 섹션을 <pre> </pre> 태그로 래핑하여 컨텐츠가 이스케이프하지 않고 구문 분석되도록 합니다.

명령

인라인 코드 블록으로 짧은 명령 이름을 참조합니다.

  • 올바른 사용: 실행 중인 클러스터의 상태를 확인하려면 ghe-cluster-status 명령을 사용합니다.

더 길거나 더 복잡한 명령에 명령 블록을 사용합니다.

  • 올바른 사용: 임의 클러스터 노드의 관리 셸에 연결하고 다음을 실행하여 예약된 모드에 따라 유지 관리 모드를 사용하도록 설정합니다.

    ghe-cluster-maintenance -s

$과(와) 같은 명령 프롬프트를 포함하지 마세요. 명령 이름에서 인라인 링크를 사용하지 않습니다.

Outputs

명령의 출력을 표시하는 경우 사용자가 명령을 복사하여 붙여넣고 수정 없이 실행할 수 있도록 예시의 출력을 주석으로 처리하세요.

  • 올바른 사용:

    git lfs install
# Git LFS initialized.

  • 잘못된 사용:

    $ git lfs install
> Git LFS initialized.

예제

코드 예제가 더 큰 파일을 참조하는 경우 사용자가 자신의 코드를 컨텍스트에서 편집할 수 있도록 파일의 관련 섹션을 표시합니다.

  • 올바른 사용:
on:
  schedule:
    - cron:  "40 19 * * *"
  • 잘못된 사용:
schedule:
  - cron:  "40 19 * * *"

파일 이름 및 디렉터리 이름

고정폭 글꼴로 백틱을 사용하여 파일 이름 및 디렉터리 이름의 참조 서식을 지정합니다. 파일 형식이 일반적으로 README 파일의 모든 대문자 표시와 같은 특정 대문자 사용 규칙을 따르는 경우 설정된 규칙을 사용합니다.

  • 올바른 사용: README.md 파일에 리포지토리에 대한 정보를 추가합니다.
  • 올바른 사용: .github/workflows/ 디렉터리에서 example-workflow.yml 파일을 만듭니다.
  • 잘못된 사용: .github/workflows/ 디렉터리에서 example-workflow.yml 파일을 만듭니다.
  • 잘못된 사용: example.js 파일을 삭제합니다.

들여쓰기

작업 및 워크플로 파일과 같은 YAML 예제에서는 두 개의 공백을 사용하여 중첩된 목록 내의 줄을 들여쓰고 시퀀스를 차단합니다.

  • 올바른 사용:
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python }}

다시 사용 가능한 내용을 들여쓰려면 다음을 참조하세요 data/reusables/README.md.

워크플로 예약

너무 많은 워크플로가 한 번에 실행되면 워크플로 실행이 지연됩니다. 많은 사용자가 GitHub Docs에서 코드를 복사하므로 사용자가 혼잡한 시간을 이용하지 않는 예제를 사용해야 합니다.

  • 가장 혼잡한 시간이므로 해당 시간에 실행되는 예시를 사용하지 마세요.
  • 필요 이상으로 자주 실행되는 예제를 사용하지 마세요. 예를 들어 예제가 5분마다 실행보다 30분마다 실행이 적합하지는 않은지 고려합니다.
  • 예제마다 다른 시간을 사용합니다.

강조하기

볼드를 사용하여 문장의 단어 또는 일부를 강조합니다. 강조를 과하게 사용(연속 단어 5개 이하)하지 말고 정상 시력을 가진 사용자의 스캔 가능성을 높이기 위한 시각적 보조 수단이라는 점을 기억하세요.

  • 개체 틀 텍스트에 대문자 등 다른 서식이 적용된 단어는 굵게 표시하지 마세요.
  • 접근성을 위해 의미나 강조를 전달하는 유일한 방법으로 굵게 표시를 사용하지 마세요.

예시:

  • 사용: 관리되는 사용자 계정은 공용 콘텐츠를 만들거나 엔터프라이즈 외부에서 공동 작업할 수 없습니다.
  • 잘못된 사용: 제목 옆에 새 키에 대한 설명이 포함된 레이블을 추가합니다.

오류 메시지

GitHub 제품 또는 인터페이스의 오류 메시지 텍스트를 문서에 포함하는 경우 메시지가 표시되는 인터페이스에 따라 텍스트의 서식을 지정합니다.

  • 메시지가 GitHub의 웹 인터페이스 또는 GitHub Desktop 또는 GitHub Mobile과(와) 같은 그래픽 클라이언트 앱에 표시되는 경우 메시지를 UI의 다른 텍스트와 같이 처리합니다. 자세한 내용은 사용자 인터페이스 텍스트를 참조하세요.

  • 메시지가 명령줄 인터페이스, 로그 출력 또는 API의 응답에 표시되는 경우 텍스트를 정확하게 재현하고 백틱을 사용하여 고정 폭 글꼴을 통해 메시지의 서식을 지정합니다.

콘텐츠 만료

일반적으로 만료되는 콘텐츠를 문서화하지 마세요. GitHub Docs을(를) 방문하는 모든 사람은 정보가 정확하고 최신 상태임을 확신해야 합니다.

만료될 것으로 알고 있는 콘텐츠를 문서화해야 하는 경우 콘텐츠 Linter를 사용하여 콘텐츠의 만료 날짜에 태그를 지정하고 추적할 수 있습니다. 이렇게 하면 콘텐츠가 오래된 것으로 플래그를 지정하고 콘텐츠 자체 외부에서 만료 날짜를 추적하지 않습니다. 만료되는 콘텐츠 태그의 서식을 지정하는 방법에 대한 자세한 내용은 콘텐츠 Linter 사용을(를) 참조하세요.

각주

가능한 경우 각주를 사용하지 마세요. 대신 경고를 사용하거나 다른 방법으로 정보를 표시할 수 있는지를 고려합니다. NICE.org.uk에서 각주에 대한 대안의 몇 가지 예를 참조하세요.

각주를 사용해야 하는 경우 Markdown 네이티브 각주([^1])를 사용합니다. 각주 표식은 표식에 대한 백링크와 함께 페이지 아래쪽에 나열되는 각주 참조로 하이퍼링크됩니다.

사용하는 식별자(문자, 단어)에 관계없이 각주가 순차적 숫자로 렌더링됩니다.

MonaUrsulaPaulDavy Jones1
좋아하는 취미Shipping codeTricking mermaids2스포츠 예측하기유령 선원
힘을 좋은 곳에 사용합니다.예아니요예아니요
| | Mona | Ursula | Paul | Davy Jones[^1] |
|---|---|---|---|---|
|Favorite pastime| Shipping code | Tricking mermaids[^2] | Predicting sports | Haunting seafarers |
|Uses powers for good| Yes | No | Yes | No |
[^1]: Not to be confused with Davy Jones of The Monkees
[^2]: Also humans

헤더

헤더는 해당 내용 아래에 있는 콘텐츠를 적절하게 설명해야 합니다. 헤더는 제목 작성 지침을 따르거나 질문으로 작성할 수 있습니다. 헤더에 문장 대/소문자를 사용합니다.

문서에 헤더가 있는 경우 헤더는 반드시 H2 수준의 헤더로 시작해야 합니다. H3 및 H4 수준 헤더를 사용하여 콘텐츠를 관련 그룹으로 더 구성할 수 있지만 헤더 수준을 건너뛸 수는 없습니다. 헤더와 하위 헤더 사이에는 소개와 같은 텍스트 콘텐츠가 있어야 합니다.

  • 올바른 사용:

    ## HEADER (H2)

TEXT

### SUBHEADER (H3)

TEXT

#### SUBHEADER (H4)

TEXT

  • 잘못된 사용:

    ## HEADER (H2)

#### SUBHEADER (H4)

페이지의 동일한 수준에 있는 각 헤더는 고유해야 합니다.

  • 올바른 사용:

    ## Examples  (H2)

TEXT

### Prompts for writing code (H3)

TEXT

### Prompts for writing tests (H3)

TEXT

  • 올바른 사용:

    ## Prompts for writing code (H2)

TEXT

### Example (H3)

TEXT

## Prompts for writing tests (H2)

TEXT

### Example (H3)

TEXT

  • 잘못된 사용:

    ## Example prompts (H2)

TEXT

### Example (H3)

TEXT

### Example (H3)

TEXT

이미지

문서 전체에서 스크린샷, 다이어그램 및 그래프를 포함한 정적 이미지를 사용하여 텍스트 정보를 보완합니다.

문서에서 애니메이션 GIF를 사용하지 마세요.

대체 텍스트

모든 이미지에는 시각적 정보에 해당하는 텍스트를 제공하는 대체 텍스트가 포함되어야 합니다.

  • 이미지의 핵심 아이디어 또는 의미를 직접적으로 설명하지 않고 표현합니다.
  • 40~150자를 사용합니다.
  • 문장 부호로 끝을 맺습니다. 대체 텍스트는 물음표 또는 느낌표와 같은 다른 문장 부호로 끝나는 텍스트 이미지를 설명하지 않는 한, 일반적으로 마침표로 끝내야 합니다.
  • "이미지..."로 또는 "그래픽..."으로 시작하지 마세요. 화면 읽기 프로그램이 이를 자동으로 말합니다.
  • "…의 스크린샷" 또는 "…를 표시하는 다이어그램"과 같이 그래픽 _유형_으로 시작하세요.
  • 문서 텍스트에서 UI 요소를 설명하는 데 사용한 표준 언어를 따릅니다.
  • 메뉴 항목의 이름과 같은 여러 단어 제목을 큰따옴표("") 안에 넣습니다.
  • 이미지 일부 영역이 시각적으로 강조 표시된 경우 방법을 설명합니다. 이를 통해 화면 읽기 프로그램 사용자는 시각적 언어 관점에서 무엇을 찾아야 하는지 알고 친구/동료에게 설명할 수 있습니다.

스크린샷의 대체 텍스트

대체 텍스트는 스크린샷 콘텐츠를 볼 수 없는 사용자에게 도움이 되도록 스크린샷의 콘텐츠에 대한 간단한 설명을 제공합니다.

  • 대체 텍스트는 모든 세부 정보가 아니라 이미지와 가장 관련성이 큰 요소만 포함합니다.
  • 대체 텍스트는 GitHub 인터페이스 사용 지침을 제공하기 위한 것이 아닙니다. 이러한 지침은 함께 제공되는 문서 텍스트에 포함되어야 합니다.
형식

Product name + UI element의 스크린샷. UI element + state of the element/controls, 그리고 해당하는 keyboard shortcut XYZ가 진한 주황색 윤곽선으로 강조 표시됩니다.

  • Product name의 경우, 단순히 "GitHub" 대신에 "GitHub Actions" 또는 "GitHub 리포지토리"와 같이 GitHub 제품 또는 기능 이름을 사용합니다.
  • 복사를 실행할 때와 마찬가지로 GitHub 단어에 변수를 사용합니다. {% data variables.product.prodname_dotcom %}
  • 작성된 설명서와 일치하도록 UI 요소를 설명합니다.
  • 명확성을 위해 필요한 경우 단어 순서를 유연하게 사용합니다.
    • 예를 들어 "Visual Studio Code 디버그 메뉴의 스크린샷..." 대신 "Visual Studio Code 디버그 메뉴의 스크린샷..."으로 작성하여 여러 명사를 연속으로 사용하지 않도록 합니다.
예제

리포지토리 테이블별 GitHub 커미터의 스크린샷. 가로형 케밥 메뉴 아이콘과 "CSV 보고서 다운로드" 단추가 진한 주황색 윤곽선으로 강조 표시됩니다.

GitHub 리포지토리에 있는 파일 옵션의 스크린샷. "코드"라는 레이블이 지정된 드롭다운 메뉴를 나타내는 화살표가 있는 단추가 진한 주황색 윤곽선으로 강조 표시됩니다.

GitHub 리포지토리의 파일 옵션 스크린샷. "코드"라는 레이블이 지정된 드롭다운 메뉴를 나타내는 화살표가 있는 단추가 진한 주황색 윤곽선으로 강조 표시됩니다.

다이어그램 및 그래프의 대체 텍스트

다이어그램 또는 그래프가 전달하는 정보를 해당 페이지에서 텍스트로 설명합니다.

대체 텍스트를 사용하여 웹 페이지 텍스트를 복제하지 않고 이미지의 핵심 아이디어를 표현합니다.

예시

GitHub Actions 실행기를 지명된 실행기 클래스에 자동으로 추가한 다음 특정 작업에서 요청할 수 있는 5단계 프로세스를 보여 주는 다이어그램.

예를 들어 Actions 설명서에서 이 다이어그램에 대한 설명을 참조하세요.

명령줄 인터페이스 이미지에 대한 대체 텍스트

명령줄 인터페이스의 스크린샷을 사용하여 명령과 해당 출력을 전달하지 마세요. 대신 사용자가 사용해야 하는 명령을 직접 제공하세요. 자세한 내용은 스타일 가이드의 명령 섹션을 참조하세요.

명령줄 인터페이스의 스크린샷을 사용하여 사용자 인터페이스 요소를 표시하는 경우 스크린샷에 대한 표준 대체 텍스트 지침을 따릅니다.

이미지의 파일 이름

이미지 파일 이름을 지정할 때는 이미지 파일 이름에 이름, 작업, UI 요소를 포함시켜 서술적으로 지정합니다. 제품 언어를 미러링합니다. 케밥식을 사용합니다. 파일 이름에는 Liquid 조건부를 사용하지 마세요. 이미지를 바꾸는 경우 정확한 파일 이름을 사용합니다.

  • 올바른 사용: data-pack-purchase-button.png
  • 잘못된 사용: purchase_button.png
  • 잘못된 사용: purchase-button-for-admins.png

스크린샷

이미지 만들기와 버전 관리 방법에 대한 자세한 내용은 스크린샷 만들기 및 업데이트를 참조하세요.

다이어그램

다이어그램을 만드는 방법에 대한 자세한 내용은 GitHub Docs에 대한 다이어그램 만들기을(를) 참조하세요.

포괄적 언어

세계에서 가장 큰 개발자 커뮤니티의 본고장인 GitHub은(는) 우리가 하는 모든 측면에서 다양성과 포괄성을 촉진하기 위해 최선을 다하고 있습니다. 우리의 모든 설명서는 전 세계의 매우 다양한 상황에 있는 사람들로 구성된 사용자들을 포용하고 존중합니다. 설명서를 작성할 때 포용적이고 인종을 차별하지 않으며 접근성이 좋은 단어를 사용합니다.

각각의 단어는 작아 보이지만 함께 모이면 커뮤니티 소속감과 공정함을 만들 수 있습니다. 모든 단어와 스타일 선택에서 이해심을 보이세요. 사람과 커뮤니티를 언급할 때는 정확해야 합니다.

사용할 용어사용하지 말아야 할 용어
허용 목록화이트리스트
거부 목록블랙리스트
기본/주요 분기마스터 분기

포괄적 언어에 대한 리소스

Microsoft 스타일 가이드는 비차별적 의사소통, 접근성 용어 및 모두를 위한 글쓰기와 관련된 자료를 제공합니다.

모두가 사용할 수 있는 포괄적 언어 및 스타일에 대해 학습할 수 있는 추가 자료:

바로 가기 키

바로 가기 키를 표시하려면 다음 차이점을 제외하고는 Microsoft 스타일 가이드를 따릅니다.

  • 각 개별 키에 HTML <kbd> 태그를 사용합니다.

    • 올바른 사용: <kbd>Command</kbd>+<kbd>B</kbd>
    • 잘못된 사용: Command+B

  • Apple 보조 키는 기호 대신 전체 단어를 사용합니다.

    • 올바른 사용: Command
    • 잘못된 사용: ⌘

  • 특수 문자 키는 전체 단어가 아닌 기호를 사용합니다.

    • 올바른 사용: ., ,, 그리고 →.
    • 잘못된 사용: Period, Comma, 그리고 Right arrow.

사용법 하이라이트트

다음은 설명서에 바로 가기 키를 제공하는 방법에 대한 몇 가지 사용법 하이라이트입니다.

  • 기본 구문은 공백 없이 키 조합 간에 +을(를) 사용해서 키를 표시하는 것입니다.

    • 올바른 사용: <kbd>Command</kbd>+<kbd>B</kbd>, 이는 Command+B로 표시됩니다.
    • 잘못된 사용: <kbd>Command</kbd> + <kbd>B</kbd> 또는 <kbd>Command + B</kbd>, 이는 Command + B 또는 Command + B로 표시됩니다.

  • 일반 참조 및 바로 가기 키의 문자 키를 항상 대문자로 표시합니다.

    • 올바른 사용: Command+B
    • 잘못된 사용: Command+b.

  • 각 운영 체제에 해당하는 올바른 보조 키를 사용합니다.

    참고: Windows 및 Linux에는 Ctrl로 약어가 있지만 Mac에는 Control로 전체 철자가 표시됩니다.

    • Windows 및 Linux용

      • 올바른 사용: Ctrl, Alt.
      • 잘못된 사용: Control

    • Mac용

      • 올바른 사용: Command, Option, Control.
      • 잘못된 사용: Cmd, ⌘, Opt, ⌥, Ctrl, ⌃

  • 키 조합을 연속적인 키와 혼동하지 마세요.

    • Command+B는 사용자가 Command 키를 누른 상태로 B 키를 누르는 것을 나타냅니다.
    • G I는 사용자가 G 키를 누른 후 I 키를 누르는 것을 나타냅니다.

  • 여러 운영 체제의 바로 가기 키를 설명할 때 바로 가기 키 뒤의 대괄호 안에 운영 체제를 표시합니다. 먼저 Mac 바로 가기를 설명한 다음 Windows/Linux를 설명합니다.

    • 올바른 사용: <kbd>Command</kbd>+<kbd>B</kbd> (Mac) or <kbd>Ctrl</kbd>+<kbd>B</kbd> (Windows/Linux), 이는 다음과 같이 표시됩니다.

      Command+B (Mac) 또는 Ctrl+B (Windows / Linux)

    • 잘못된 사용: <kbd>Ctrl</kbd>+<kbd>B</kbd> or <kbd>Command</kbd>+<kbd>B</kbd>, 이는 다음과 같이 표시됩니다.

      Ctrl+B 또는 Command+B

사용이 허가된 콘텐츠

GitHub Docs은(는) CC-BY 라이선스에 따라 라이선스가 부여됩니다. 문서에서 라이선스가 허가된 콘텐츠를 다시 사용하거나 수정하는 경우 라이선스가 호환되고 저작자가 올바르게 명시되었는지 확인해야 합니다.

라이선스 저작자 표시에 재사용 허용을 만들지 마세요. 프로젝트에 허용된 라이선스를 정확히 사용해야 하므로 사용되는 문서에 모든 저작자 표시를 반드시 정확하게 작성해야 합니다.

콘텐츠 재사용의 적법성이 확실하지 않으면 법률 자문을 받으세요. 아래에 나열되지 않은 라이선스로 콘텐츠를 추가하는 경우 콘텐츠를 게시하기 전에 법적 검토를 받아야 합니다.

MIT 라이선스로 허가된 콘텐츠 저작자 표시

MIT 라이선스로 허가된 콘텐츠를 다시 사용하거나 수정하는 경우 콘텐츠가 표시될 때 MIT 라이선스를 표시해야 합니다.

MIT 라이선스로 허가된 콘텐츠가 포함된 문서의 끝부분에는 다음을 작성합니다.

  • Legal notice(으)로 제목을 붙인 헤더를 생성하세요.
  • 콘텐츠 출처를 표시하고 MIT 라이선스에 따라 허가된 콘텐츠임을 표시하세요. 프로젝트 링크를 포함합니다.
  • 코드 블록에 저작자 표시를 하는 프로젝트의 MIT 라이선스 텍스트 전체를 붙여넣습니다.

MIT 라이선스 저작자 표시 예시

다음은 예시에 불과합니다. 항상 저작자 표시를 하는 프로젝트의 라이선스 텍스트를 사용합니다.

## Legal notice

Portions have been adapted from [PROJECT](/LINK/TO/PROJECT) under the MIT license:

```
MIT License

Copyright YEAR COPYRIGHT-HOLDER

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
```

줄 바꿈

일반 텍스트의 경우 원본에 시각적 공간을 만드는 대신 줄 바꿈을 사용하여 원본의 단락을 구분합니다 (연속된 두 줄 바꿈). 특히 목록에서 불필요한 줄 바꿈을 사용하지 않습니다.

링크는 사용자를 추가 정보에 연결하고 여러 문서를 읽어야 하는 작업을 진행하는 데 사용됩니다.

링크 사용을 최소화합니다. 너무 많은 링크를 포함하면 주요 콘텐츠에 방해가 되거나 사람들이 집중력을 빼앗길 수 있습니다. 모든 링크는 사용자 경험의 컨텍스트에서 고려해야 합니다. 왜 우리가 이 링크로 누군가를 보내야 할까요? 어떻게 정상 궤도로 되돌려 작업을 완료하게 할 수 있을까요?

링크를 추가하기 전에 누가 링크를 방문하여 콘텐츠를 이해해야 하거나 GitHub를 성공적으로 사용해야 하는지 결정합니다.

  • 링크가 필요하지 않은 경우 제거합니다.
  • 링크가 문서의 주요 항목과 관련이 있고 다른 사용자가 계속 학습할 수 있게 하지만 반드시 작업을 완료하지는 않는 경우, 문서의 끝으로 링크를 이동하여 더 읽게 하는 방식을 고려합니다.
  • 링크가 누군가를 어느 프로세스의 다음 단계로 이동하게 하는 경우 문서 끝에 있는 다음 단계 섹션에 링크를 포함합니다.
  • 링크가 작업을 완료하거나 단계 문제를 해결하는 데 중요한 정보를 제공하는 경우 문서의 본문에 링크를 포함합니다.

링크는 일관적이고, 최대한 많은 사용자가 액세스할 수 있어야 하며, 변환 가능하고 명확해야 합니다. 사용자는 주어진 링크가 어디로 이동하는지, 자신이 실현하고자 하는 목표와 어떤 관련이 있는지 알아야 합니다.

링크를 사용하는 몇 가지 모범 사례:

  • 링크는 유의미해야 하며 높은 가치의 사용자 경험을 제공해야 합니다. 링크를 신중하게 연결하세요.
  • 동일한 문서에서 동일한 링크를 두 번 이상 반복하지 마세요.
  • 같은 문서의 섹션에 대한 링크 후 "이 문서의 앞/뒷부분"을 추가하는 것이 좋습니다.
  • REST 문서의 특정 시점 버전에 연결해야 하는 경우가 아니면 REST 링크에 apiVersion 쿼리 매개 변수를 포함시키지 마세요(드문 경우여야 합니다).

링크의 목적이 무엇인지 컨텍스트만으로 명확하게 밝힐 수 있는 경우 "참조"만으로 링크를 소개할 수도 있습니다. 컨텍스트가 명확하지 않은 경우, 구문이나 문장을 사용해 링크를 소개합니다. 예를 들어 "자세한 내용은 다음을 참조" 또는 "X에 관한 자세한 내용은 Y를 참조하세요."를 사용하면 됩니다.

설명서 문서의 제목이나 외부 웹 페이지의 제목을 링크 텍스트로 사용하세요. GitHub Docs 사이트의 다른 문서를 가리키는 모든 링크의 경우, 해당 링크 텍스트의 특수 키워드 AUTOTITLE을(를) 사용합니다. 콘텐츠 마크업 참조의 세부 정보를 참조하세요.

링크에 스타일을 적용하거나 따옴표로 묶지 마세요.

  • 다른 페이지에 대한 링크: See [AUTOTITLE](/PATH/TO/PAGE).
  • 다른 페이지 구역에 대한 링크: For more information, see [AUTOTITLE](/PATH/TO/PAGE#SECTION-LINK).

인라인 링크는 사용하지 마십시오. 인라인 링크에서는 문장 내의 단어에 하이퍼링크가 설정되어 있지만 그 문장에 링크를 포함하는지 아닌지 표시하는 추가 단어가 없습니다. 이렇게 하면 변환하고 읽기가 어려울 수 있습니다.

하이퍼링크 내에 문장 부호를 포함하지 마세요.

  • 올바른 사용: OAuth2 tokens can be acquired programmatically for applications that are not websites. For more information, see [AUTOTITLE](/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) and [AUTOTITLE](/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps).
  • 잘못된 사용: Read [more about OAuth2](/apps/building-integrations/setting-up-and-registering-oauth-apps/). Note that OAuth2 tokens can be [acquired programmatically](/enterprise-server@2.22/rest/reference/oauth-authorizations/#create-a-new-authorization), for applications that are not websites.

때로는 GitHub Docs의 한 버전을 다른 버전에 연결해야 할 수도 있습니다. 같은 페이지의 다른 버전에 연결하려는 경우 currentArticle 속성을 사용해야 합니다.

예를 들어 Free(무료), Pro(프로), 팀 버전의 조직의 GitHub Pages 사이트 게시 관리은(는) 다음과 같이 동일한 문서의 GitHub Enterprise Cloud 버전에 연결될 수 있습니다.

You can choose to allow or disallow the publication of GitHub Pages sites.

Organizations that use {% data variables.product.prodname_ghe_cloud %} can choose to allow publicly published sites, privately published sites, both, or neither. For more information, see [the {% data variables.product.prodname_ghe_cloud %} documentation](/enterprise-cloud@latest/{{ currentArticle }}).

다른 버전의 다른 문서에 연결하려면 다음 형식을 사용합니다.

For more information, see [ARTICLE TITLE](/) in the VERSION documentation.

다른 버전의 동일한 문서에 연결하려면 다음 형식을 사용합니다.

For more information, see [the VERSION documentation](/VERSION/{{ currentArticle }}).

특정 버전에 연결하려면 경로에 버전을 포함해야 합니다 (예: /enterprise-cloud@latest/{{ currentArticle }}).

문서의 특정 섹션에 대한 링크는 누군가가 링크를 따라가면 자신이 올바른 위치에 있다는 것을 이해할 수 있을 만큼 충분한 설명을 담아야 합니다.

같은 문서의 특정 헤더에 연결하려면 다음 형식을 사용합니다.

For more information, see [HEADER TITLE](#HEADER-TITLE), later in this article.

동일한 페이지 섹션 링크에서는 AUTOTITLE이(가) 작동하지 않습니다. 대신 전체 헤더 텍스트를 입력해야 합니다.

다른 문서의 특정 헤더에 연결하려면 다음 형식을 사용합니다.

For more information, see [AUTOTITLE](PATH-TO-ARTICLE#HEADER-TITLE).

다른 문서에서 두 개 이상의 특정 헤더에 연결하려면 다음 형식을 사용합니다.

For more information, see [HEADER-TITLE-1](PATH-TO-ARTICLE#SECTION-LINK-1) and [HEADER-TITLE-2](PATH-TO-ARTICLE#SECTION-LINK-2) in "ARTICLE-TITLE."

선택한 특정 도구를 사용하여 콘텐츠에 연결하는 경우 누군가가 문서의 도구 전환기 탭과 상호 작용하지 않더라도 링크가 특정 도구를 위한 것임을 분명히 해야 합니다.

For more information, see the TOOLNAME documentation in [ARTICLE TITLE](/PATH/TO/ARTICLE?tool=TOOLNAME).

다음 형식을 사용하여 학습 경로에 연결합니다.

For more information, follow the [LEARNING PATH TITLE](/) learning path.

외부 사이트에 연결할 때는 링크 컨텍스트에 가장 유용한 리소스를 선택합니다. 일반 참조인 경우 전체 사이트에 연결하거나 더 유용하다면 특정 페이지에 연결할 수 있습니다.

외부 제품을 언급할 때 외부 제품의 웹 사이트에 연결할 필요는 없습니다.

외부 페이지(GitHub에서 관리되지 않는 모든 웹 사이트)에 대한 링크의 경우 전체 페이지 제목과 목적지 사이트를 입력합니다. 링크를 따옴표로 묶지 마세요.

  • 올바른 사용: See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE) in the XYZ documentation.
  • 잘못된 사용: See [PAGE-TITLE](https://some-docs.com/PATH/TO/PAGE).
  • 잘못된 사용: See [the OTHER WEBSITE](https://some-docs.com/PATH/TO/PAGE).

문서의 특정 섹션에 링크가 있다는 것을 알고 있는 경우, 해당 섹션에 앵커를 추가하여 링크를 유지할 수 있습니다. 예를 들어 외부 리소스가 한 문서의 특정 섹션에 연결되는 경우, 섹션 제목이 변경되더라도 링크가 올바른 섹션으로 연결되도록 앵커를 추가할 수 있습니다.

링크 앵커에 이 형식을 사용합니다. 앵커 이름은 유지 중인 섹션 이름이어야 합니다. HTML 주석을 사용하여 앵커를 추가하는 이유를 설명합니다.

<!-- Anchor to maintain the current example link. -->
<a name="SECTION-TITLE-THAT-MIGHT-CHANGE"></a>

목록

목록의 각 줄에서 첫 글자를 대문자로 표시합니다. 줄에 전체 문장이 포함된 경우에만 목록의 줄 끝에 마침표를 사용합니다.

term 및 해당 정의와 같이 기본 및 보조 텍스트로 구성된 항목 목록을 작성할 때는 콜론 구분 기호를 사용합니다. 보조 텍스트는 줄의 시작 부분인 것처럼 대문자로 표시해야 합니다. 예시:

  • foo: Bar를 제공하는 것입니다.
  • bar: Foo에서 제공하는 것입니다.

순서가 지정되지 않은 목록 서식 지정:

  • 목록의 항목 순서가 중요하지 않은 경우 목록 항목을 알파벳순으로 정렬합니다.
  • 순서가 중요한 경우 목록을 읽는 사람에게 중요한 순으로 정렬합니다 (예: 가장 광범위한 대상 그룹 및 적용 대상에서 보다 전문화된 대상으로 정렬).
  • 목록 항목에 별표(*)를 사용합니다.

목록을 소개할 때 컨텍스트 없이 지역화하기 어려운 “다음” 또는 “이들”과 같은 용어가 들어간 짧은 비특정 문장을 사용하지 마세요. 대신 목록의 주제를 명확하게 전달하지만 설명을 업데이트할 필요 없이 목록의 크기를 조정하거나 변경할 수 있는 설명 문장을 만듭니다.

올바른 사용:

  • GitHub 소개는 다음 문서를 참조하세요.
  • SMS 인증은 이들 국가에서 지원됩니다.

잘못된 사용:

  • GitHub을(를) 소개하는 몇 가지 문서가 있습니다. 다음을 참조하십시오.
  • SMS 인증은 50개 국가에서 지원됩니다. 여기에는 다음이 포함됩니다.

사용 권한 문 및 제품 설명

사용 권한 문 및 제품 설명을 통해 특정 역할 또는 제품을 완료해야 하는 작업을 전달합니다.

  • 사용 권한 문: 작업을 수행하거나 문서에 설명된 작업을 수행하는 데 필요한 역할입니다. 예: "엔터프라이즈 소유자."
  • 제품 설명: 작업을 수행하거나 문서에 설명된 작업을 수행하는 데 필요한 제품입니다. 예: “Copilot Business을(를) 구독하는 조직 및 엔터프라이즈 계정.”

사용 권한 문과 제품 설명은 함께 문서에서 설명하는 기능을 사용할 수 있는 독자에게 알려줍니다.

스캔 가능한 제품 설명 만들기에 대한 지침

사용 권한 및 제품 요구 사항 정의

사용 권한 문 또는 제품 설명에 속하는 정보를 고려합니다.

예를 들어 조직에서 Copilot에 대한 정책 관리 문서에 대한 사용 권한과 제품 설명을 만들 때 사용 권한 설명은 “조직에서 GitHub Copilot에 대한 정책 및 기능을 관리할 수 있는 역할은 무엇인가요?”라고 대답합니다. 그리고 제품 설명은 "사용자가 조직의 Copilot 정책 및 기능을 관리해야 하는 Copilot 구독은 무엇인가요?"라고 대답합니다.

설명이 아닌 주요 정보에 집중

사용 권한 문 및 제품 설명은 작업을 수행할 수 있는 사용자와 필요한 제품을 전달해야 합니다. 역할 또는 제품이 필요한 이유를 설명할 필요가 없습니다.

여러 역할 또는 제품이 사용 권한 문 또는 제품 설명에 적용되는 경우 순서가 지정되지 않은 목록을 사용하여 서식을 지정합니다. 문장으로 복잡한 사용 권한 문 및 제품 설명을 소개할 수 있지만, 항상 필요한 만큼의 단어만 사용하여 문서의 작업을 수행할 수 있는 사용자를 전달하려고 합니다.

인라인 링크를 사용하여 역할 또는 제품에 대한 자세한 정보를 제공할 수 있습니다. 링크 대상을 따라가는 위치가 명확하도록 연결된 텍스트가 링크 대상과 일치해야 합니다.

자리 표시자

모든 개체 틀 텍스트의 스타일을 모두 대분자로 지정합니다. 자리 표시자가 여러 단어인 경우 단어를 대시(케밥식)로 연결합니다. 개체 틀을 사용하는 경우 개체 틀을 대체할 수 있는 항목을 설명합니다. 이렇게 하면 사용자가 필요에 맞게 예제를 수정하고 보조 기술을 사용하는 사람들이 자리 표시자를 식별하는 데 도움이 됩니다.

올바른 사용:

  • 다음 예제에서 YOUR-REPOSITORY를 리포지토리 이름으로 바꿉니다. git init YOUR-REPOSITORY
  • 사용자 이름 추가를 클릭합니다. 여기서 사용자 이름은 추가하려는 인원의 사용자 이름입니다.

잘못된 사용:

  • git init your repository
  • git init <your-repository>
  • 사용자 이름 추가를 클릭합니다.

절차상 단계

절차는 사용자가 작업을 완료하기 위해 따라야 할 일련의 단계들을 제공합니다. 절차에는 항상 항상 번호 목록을 사용합니다. 작업을 완료하는 데 필요한 모든 선행 조건 또는 개념 정보를 특정 단계에 포함하지 않고 절차 전에 사용자에게 제공합니다.

각 단계에는 액션이 포함되어야 합니다. 단계가 선택 사항인지 여부를 포함하고, 단계의 이유 또는 결과를 설명하고, 액션을 완료하도록 안내하기 전에 작업의 위치를 설명하여 사용자를 올바른 방향으로 이끌 수 있습니다.

각 단계 내에서 일관된 순서를 사용하여 정보를 표시합니다.

  1. 단계가 선택 사항이면 이를 먼저 나타냅니다.
  2. 명확성을 위해 필요하거나 파괴적이거나 혼란스러운 액션의 심각도를 보강하기 위해서 단계의 이유 또는 결과를 설명합니다.
  3. 사용자가 액션을 찾을 수 있는 위치를 설명합니다.
  4. 액션.

올바른 사용: to REASON, in LOCATION, take ACTION을 선택적으로 사용하세요.

예:

  • <결제 정보> 를 클릭하세요.
  • 조직 이름 아래에서 <설정> 을 클릭합니다.
  • 변경 내용을 확인하려면 <신용 카드 제거> 를 클릭합니다.
  • 필요에 따라 계획의 세부 정보를 보려면 <세부 정보 표시> 를 클릭합니다.
  • "GitHub Sponsors"에서 스폰서 오픈 소스 기여자 오른쪽의 스폰서 금액 옆에 있는 아이콘을 클릭하고 티어 변경을 클릭합니다.

제품 이름

전체 제품 이름을 사용합니다. UI 복사 또는 API 응답과 같이 제품에서 콘텐츠를 직접 재현하는 경우가 아니라면 제품 이름을 축약하거나 줄이지 마세요. 제품 이름은 소유격이 아닙니다.

제품 이름 변수를 사용하여 제품 이름을 렌더링합니다. 단, 제품 이름을 일반 텍스트로 작성하지 마세요. 이렇게 하면 사이트 전체에서 제품 이름을 보다 쉽게 변경할 수 있으며 제품 이름에 오타를 방지할 수 있습니다. 제품 이름 변수에 대한 자세한 내용은 이 문서의 "재사용 항목 및 변수"와 github/docs 리포지토리의 데이터 디렉터리를 참조하세요.

제품 이름은 항상 단수입니다.

  • 올바른 사용: GitHub Actions을(를) 사용하면 소프트웨어 개발 워크플로를 자동화할 수 있습니다.
  • 잘못된 사용: GitHub Actions들을 사용하면 소프트웨어 개발 워크플로를 자동화할 수 있습니다.

제품 이름과 제품 기능을 구분합니다. 제품 기능은 항상 소문자입니다.

Product기능
GitHub Actions액션
GitHub Codespacescodespace
GitHub Packages패키지
GitHub PagesGitHub Pages 웹 사이트

끌어오기 요청, 주제 또는 문제와 같이 일반적으로 사용되는 기능을 대문자로 쓰지 마십시오.

제품별 규칙

이 섹션에서는 GitHub 제품에 해당하는 추가 규칙을 설명합니다.

GitHub Actions

퍼스트 파티 액션에 재사용 가능한 항목

퍼스트 파티 액션을 사용하는 코드 예제는 해당 액션에 해당하는 재사용할 수 있는 항목을 사용해야 합니다. 이렇게 하면 향후 GitHub Enterprise Server 릴리스까지 동일한 액션 버전을 사용할 수 없는 GitHub Enterprise Server와 같은 제품에서 v1에서 v2(으)로 가는 것과 같은 액션 버전 업데이트를 보다 쉽게 관리할 수 있습니다.

재사용 가능 작업은 /data/reusables/actions/에 위치하며 action-<action_name>.md와 같은 파일 이름을 갖고 있습니다.

예를 들어 예제에서 actions/checkout 액션을 사용하려면 해당하는 재사용 가능한 항목을 사용합니다.

steps:
  - name: Checkout
    uses: actions/checkout@v4

GitHub Docs의 경우 퍼스트 파티 액션이란 actions/, github/ 또는 octo-org/ 접두사를 가진 모든 액션입니다. 예를 들어 다음이 퍼스트 파티 액션입니다.

steps:
  - uses: actions/checkout@v4

써드 파티 액션에 대한 고지 사항

써드 파티 액션을 사용하는 코드 예제는 코드 블록의 일부로 다음 고지 사항을 포함해야 합니다.

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

이 고지 사항을 삽입하려면 {% data reusables.actions.actions-not-certified-by-github-comment %}의 재사용 가능한 값을 사용합니다.

GitHub Docs의 경우 써드 파티 액션이란 actions/, github/ 또는 octo-org/ 접두사가 없는 모든 액션입니다. 예를 들어 다음이 퍼스트 파티 액션입니다.

steps:
  - uses: actions/checkout@main

다음은 써드 파티 액션의 예시입니다.

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

예:

SHA에 버전 번호 고정

써드 파티 액션을 사용하는 코드 예제는 버전 번호 또는 분기 대신 항상 전체 길이의 커밋 SHA에 고정해야 합니다.

steps:
    - uses: google-github-actions/setup-gcloud@1bee7de035d65ec5da40a31f8589e240eba8fde5

GitHub Docs의 경우 써드 파티 액션이란 actions/, github/ 그리고 octo-org/ 접두사가 없는 모든 액션입니다. 예를 들어 다음이 퍼스트 파티 액션입니다.

steps:
  - uses: actions/javascript-action@main

자세한 내용은 SHA 사용을 참조하세요.

Codespaces

제품 Codespaces를 참조할 때는 다음 경우를 제외하고 항상 "GitHub"를 포함합니다.

  • shortTitle 프런트매터
  • 문서 내의 서브헤딩에서 "Codespaces"이(가) 문서 내의 어떤 곳에서 서브헤딩 이전에 이미 사용된 경우

변수: {% data variables.product.prodname_github_codespaces %} (‘GitHub Codespaces’) 및 {% data variables.product.prodname_codespaces %} (‘Codespaces’).

이 기술로 만든 원격 작업 환경의 인스턴스를 참조할 때는 소문자 c를 사용한 "codespaces"로 참조하세요. 예를 들어 "codespace를 삭제하려면" 또는 "코드스페이스를 나열하려면"과 같이 사용하세요.

파일/경로 이름을 제외하고 항상 "devcontainer" (한 단어)가 아니라 "dev container" (또는 명확해야 하는 경우 더 긴 형식인 "development container")를 사용합니다. 단일 단어를 사용하면 의도치 않게 브랜드로 간주될 수 있으며 Visual Studio Code 설명서에 사용된 두 단어 형식과도 일관성을 유지하고자 합니다.

.devcontainer 디렉터리의 devcontainer.json 대신에 .devcontainer.json을(를) 사용하는 경우 이와 함께 .devcontainer의 모든 파일을 "개발 컨테이너 구성 파일”이라고 참조하세요. 이를 "개발 컨테이너 파일" 또는 "devcontainer 파일"이라고 하여 devcontainer.json 파일을 참조하는 것으로 간주될 수 있습니다. "개발 컨테이너 구성 파일"은 Dockerfile 및 docker-compose.yml 파일을 포함하여 개발 컨테이너를 구성하는 데 사용할 수 있는 모든 파일을 나타냅니다. devcontainer.json 파일을 구체적으로 참조할 때 "개발 컨테이너 구성 파일" (단수)을 사용하지 마세요. 대신 이름으로 이 파일을 참조하세요.

GitHub Advanced Security (GHAS)

GitHub Advanced Security 요금 청구를 언급할 때는 licenses 및 active committers의 용어를 사용합니다.

용어 seats을(를) 사용하여 엔터프라이즈에서 GitHub Advanced Security를 사용할 수 있는 계정 수를 설명했습니다. 사용자가 seats라는 용어를 혼동할 수 있으므로, 2022년 가을 GitHub.com에서 이 용어를 제거했으며 GHES 3.7 이후 버전에서는 이 용어를 사용하지 않습니다.

Personal access tokens

GitHub에는 두 가지 유형의 personal access tokens이(가) 있습니다.

  • Fine-grained personal access tokens: 리포지토리 액세스 및 권한에 대한 세분화된 제어 제공
  • Personal access token (classic): 범위를 사용하고 토큰 소유자가 액세스할 수 있는 모든 리포지토리에 액세스를 허용합니다.

일반적으로 변수를 사용하여 이러한 유형의 토큰과 personal access tokens을(를) 참조해야 합니다.

  • 일반적으로 personal access token을(를) 참조할 때 {% data variables.product.pat_generic %} 또는 {% data variables.product.pat_generic_caps %}을(를) 사용합니다. UI 텍스트와 일치하기 위해 구문의 첫 글자가 대문자인 경우("Personal Access Token") {% data variables.product.pat_generic_title_case %}을(를) 사용합니다.
  • fine-grained personal access token을 참조하도록 {% data variables.product.pat_v2 %} 또는 {% data variables.product.pat_v2_caps %}을(를) 사용합니다.
  • personal access token (classic)을 참조하도록 {% data variables.product.pat_v1 %}, {% data variables.product.pat_v1_plural %}, {% data variables.product.pat_v1_caps %} 또는 {% data variables.product.pat_v1_caps_plural %}을(를) 사용하세요.

GitHub의 personal access tokens에 대한 자세한 내용은 개인용 액세스 토큰 관리을(를) 참조하세요.

문장 부호

표준 미국 영어 문장 부호 규칙을 따릅니다. 자세한 지침은 Microsoft 스타일 가이드의 “문장 부호”를 참조하세요.

릴리스 정보

GitHub Docs에 있는 릴리스 정보 집합은 GitHub Enterprise Server(GHES)와 같이 제품의 버전이 지정된 릴리스에 대한 관리자 또는 사용자 측 변경 내용을 이용자에게 알려줍니다. 릴리스 정보는 릴리스 정보에 표시됩니다.

좋은 릴리스 정보는 변경 내용에 대한 사용자의 질문에 순차적으로 답변하는 몇 개의 문장으로 구성됩니다. 자세한 내용은 릴리스 정보 콘텐츠 형식을(를) 참조하세요.

한 집합의 각 릴리스 정보는 다음 변경 내용 중 하나를 설명합니다.

  • 기능: 새로운 동작 또는 기능
  • 보안 수정: 보안에 영향을 주는 결함 또는 예기치 않은 동작 수정
  • 버그 수정: 결함 또는 예기치 않은 동작 수정
  • 변경 내용: 이전 동작에서 유의미하게 변경된 내용
  • 알려진 문제: GitHub이(가) 식별했지만 우선 순위를 지정할 수 없거나 아직 우선 순위가 지정되지 않은 문제
  • 사용 중단: 기능 또는 동작 제거
  • 오류: 부정확한 릴리스 정보 또는 설명서 수정

릴리스 정보 추가 또는 업데이트와 릴리스 정보 제거에서도 릴리스 정보 업데이트와 관련된 지침을 검토할 수 있습니다.

기능

기능에 대한 릴리스 정보는 새로운 동작을 요약합니다. 일반적으로 기능에 대한 정보는 기능 릴리스의 일부일 뿐입니다.

기능에 대한 릴리스 정보 작성

기능에 대한 릴리스 정보는 다음 질문에 답변합니다.

  1. 이 새로운 기능이 내 역할 또는 액세스 권한에 적용되나요?
  2. 이 기능은 어떤 요구 사항을 충족하나요?
  3. 이 기능은 무엇인가요?
  4. 해당하는 경우, 어디에서 기능에 대해 자세히 알아볼 수 있나요?

대상 그룹 (1)은 기능 사용에 대한 설명 (3)을 통해 요구 사항에 대한 설명 (2)을 할 수 있습니다. 자세한 내용은 “ARTICLE TITLE” (4)을(를) 확인하세요.

  • 기능 제목 아래의 섹션에서 각 기능을 분류합니다.
  • 현재 시제로 작성합니다.
  • 반복과 불필요한 단어를 줄이기 위해 "지금"은 일반적으로 생략합니다.
  • 행위자와 영향을 명확히 하기 위해 가능한 경우 수동 언어를 사용하지 마세요.

기능 릴리스 정보 예시

  • 사이트 관리자는 로그인 시도에 대한 트래픽률 제한과 트랙픽률 제한을 초과한 후의 잠금 기간을 구성해서 관리 콘솔의 보안을 강화할 수 있습니다. 자세한 내용은 속도 제한 구성을 참조하세요.

  • 엔터프라이즈 소유자는 사용자가 리포지토리를 포크할 수 있는 위치를 제어할 수 있습니다. 포크는 조직의 미리 설정된 조합, 부모 리포지토리와 같은 조직, 사용자 계정 또는 모든 곳으로 제한될 수 있습니다. 자세한 내용은 엔터프라이즈에서 리포지토리 관리 정책 적용을 참조하세요.

  • 사용자는 geoJSON, topoJSON 및 STL 다이어그램을 사용하여 파일을 만들고 웹 인터페이스에서 다이어그램을 렌더링할 수 있습니다. 자세한 내용은 비 코드 파일 작업을 참조하세요.

보안 수정 사항

보안 수정에 대한 릴리스 정보는 제품에서 보안 관련 문제를 악용하는 것을 완화하거나 방지하는 변경 사항을 요약합니다. 일반적으로 보안 수정에 대한 정보는 패치 릴리스의 일부일 뿐입니다.

보안 수정에 대한 릴리스 정보 작성

보안 수정에 대한 릴리스 정보는 다음 질문에 답변합니다.

  1. 해당하는 경우 수정된 취약성에 대한 NVD 취약성 심각도 등급은 무엇인가요?
  2. 공격자가 취약성을 악용하여 수행할 수 있는 공격은 무엇인가요?
  3. 어떤 유형의 취약성을 악용할 수 있나요?
  4. 해당하는 경우, 취약성의 CVE 식별자(보류 중 또는 활성)는 무엇인가요?
  5. 취약성이 GitHub 버그 장려금 프로그램을 통해 보고되었나요?

심각도 (1): 공격자는 악용에 대한 설명 (3)을 통해 영향에 대해 설명 (2)할 수 있습니다. GitHub는 GitHub 버그 장려금 프로그램 (5)을 통해 보고된 취약성에 대해 CVE ID인 CVE-####-##### (4)을(를) 요청했습니다.

보안 수정에 대한 릴리스 정보 예시

  • 미디엄: 공격자가 Markdown REST API에 대한 병렬 요청으로 인스턴스에 바인딩되지 않은 리소스 소모를 일으킬 수 있습니다. 이 문제를 완화하기 위해 GitHub에서 CommonMarker를 업데이트했습니다. GitHub에서 이 취약성에 대해 CVE ID CVE-2022-39209를 요청했습니다.

  • 미디엄: 끌어오기 요청 미리 보기 링크가 URL을 제대로 삭제하지 않았기 때문에 공격자가 인스턴스의 웹 UI에 위험한 링크를 포함시킬 수 있습니다. 이 취약성은 GitHub 버그 장려금 프로그램을 통해 보고되었습니다.

기본 이미지 및 패키지 업데이트

또한 이러한 업데이트는 종종 보안 문제를 다루므로 "보안 수정" 섹션에 기본 이미지 및 종속 패키지 업데이트를 포함합니다. 다음 참고 사항에서 이러한 모든 업데이트를 통합합니다.

패키지가 최신 보안 버전으로 업데이트되었습니다.

버그 수정

버그 수정에 대한 릴리스 정보는 원치 않거나 예기치 않은 동작에 대한 수정을 설명합니다. 일반적으로 버그 수정에 대한 정보는 패치 릴리스의 일부일 뿐입니다.

버그 수정에 대한 릴리스 정보 작성

버그 수정에 대한 릴리스 정보는 다음 질문에 답변합니다.

  1. 이 동작이 내 역할 또는 액세스 권한에 영향을 주었나요?
  2. 수정하기 전에 사용자가 경험하는 동작은 무엇이었나요?

대상 그룹 (1) 동작 에 대한 설명 (2).

  • 이제 버그가 수정되었으므로 과거 시제로 기록합니다.
  • "버그를 수정했습니다..." 또는 "문제를 해결했습니다..."와 같은 언어는 암시적이고 불필요합니다.
  • 반복과 불필요한 단어를 줄이기 위해 "지금"은 일반적으로 생략합니다.
  • 행위자와 영향을 명확히 하기 위해 가능한 경우 수동 언어를 사용하지 마세요.
  • 릴리스 정보에 오류 메시지가 포함된 경우 오류 메시지의 지침에 따라 메시지의 서식을 지정합니다.

버그 수정에 대한 릴리스 정보 예시

  • 사용자가 푸시 보호를 사용하도록 설정된 리포지토리를 가져온 후에 보안 개요의 "보안 적용 범위" 보기에 리포지토리가 즉시 표시되지 않았습니다.

  • GitHub Actions이(가) 활성화된 인스턴스에서는 작업이 큐에 들어온 후 일치하는 실행기 그룹을 사용할 수 있게 되었더라도 작업을 처음 큐에 대기할 때 일치하는 실행기 그룹을 사용할 수 없는 경우 GitHub Actions에 대한 워크플로 작업이 시작되지 않습니다.

  • 사이트 관리자가 인스턴스 노드에서 SSH를 통해 실행한 명령이 /var/log/ssh-console-audit.log에 기록되지 않았습니다.

변경

변경에 대한 릴리스 정보는 중요하지만 사소한 기존 동작의 변경에 대해 설명합니다. 변경에 대한 정보는 다음 질문에 답변합니다.

변경 내용에 대한 릴리스 정보 작성

변경에 대한 릴리스 정보는 다음 질문에 답변합니다.

  1. 이 동작이 내 역할 또는 액세스 권한에 영향을 주었나요?
  2. 변경 내용이 해결하거나 방지한 문제는 무엇인가요?
  3. 새로운 동작은 무엇인가요?
  4. 관련된 경우 변경 전의 동작은 무엇인가요?

대상 그룹 (1) / 문제 변경 해결에 대한 설명 (2) 새 동작에 대한 설명 (3) 이전 동작에 대한 설명 (4).

  • 변경 내용은 해당 릴리스에 적용되므로 현재 시제로 변경 내용에 대한 정보를 작성합니다.
  • 반복과 불필요한 단어를 줄이기 위해 "지금"은 일반적으로 생략합니다.
  • 행위자와 영향을 명확히 하기 위해 가능한 경우 수동 언어를 사용하지 마세요.
  • 종종 대상 그룹은 생략됩니다.
  • 유용한 경우 GitHub Docs의 관련 링크를 포함합니다.

변경에 대한 릴리스 정보 예시

  • GitHub Advanced Security 라이선스가 있는 인스턴스에서 비밀 검사의 사용자 지정 패턴을 작성하는 사용자는 최대 2,000자까지 일치해야 하거나 일치하지 않아야 하는 식을 제공할 수 있습니다. 이 제한은 1,000자에서 증가했습니다.

  • SAML 매핑을 검토하거나 수정해야 하는 관리자의 경우 ghe-saml-mapping-csv -d의 출력 기본 경로는 /tmp 대신 /data/user/tmp입니다. 자세한 내용은 명령줄 유틸리티를 참조하세요.

  • 여러 노드가 있는 인스턴스에서 Git 작업의 성공과 관련된 일시적인 문제를 방지하기 위해 GitHub Enterprise Server은(는) SQL 쿼리를 시도하기 전에 MySQL 컨테이너의 상태를 확인합니다. 시간 제한 기간도 단축되었습니다.

알려진 문제

알려진 문제에 대한 릴리스 정보는 GitHub가 식별했지만 아직 우선 순위를 지정할 수 없거나 아직 우선 순위가 지정되지 않은 문제를 설명합니다.

알려진 문제에 대한 릴리스 정보 작성

알려진 문제에 대한 릴리스 정보는 다음 질문에 답변합니다.

  1. 이 동작이 내 역할 또는 액세스 권한에 영향을 주나요?
  2. 표시되는 오류 메시지 또는 기타 인식할 수 있는 UI 요소는 무엇인가요?
  3. 조치가 필요한가요? 그렇다면 무엇을 해야 하나요?

대상 그룹 (1) 문제에 대한 설명 (2) 동작의 세부 정보 (3) 다음 단계 (4).

  • 행위자와 영향을 명확히 하기 위해 가능한 경우 수동 언어를 사용하지 마세요.
  • 반복과 불필요한 단어를 줄이기 위해 "지금"은 일반적으로 생략합니다.
  • 릴리스 정보에 오류 메시지가 포함된 경우 오류 메시지의 지침에 따라 메시지의 서식을 지정합니다.
  • 유용한 경우 GitHub Docs의 관련 링크를 포함합니다.
  • 알려진 문제는 GitHub Docs의 콘텐츠 유형이기도 합니다. 자세한 내용은 콘텐츠 형식 문제 해결을(를) 참조하세요. 유용한 경우 문서의 보다 심층적이고 상황에 맞는 관련 콘텐츠를 작성하거나 연결합니다.

알려진 문제에 대한 릴리스 정보 예시

  • 읽기 권한이 있는 다른 사용자가 토론을 만들 수 있도록 사용자가 허용하는 리포지토리 옵션을 활성화한 후에는 이 기능을 사용할 수 없습니다.

  • 관리자가 구성 실행을 시작한 후 No such object error이(가) Notebook 및 Viewscreen 서비스의 유효성 검사 단계에서 발생할 수 있습니다. 서비스가 여전히 올바르게 시작되어야 하므로 이 오류를 무시할 수 있습니다.

사용 중단

사용 중단 릴리스 정보에는 GitHub이(가) 제거했거나 제거할 계획이 있는 동작이나 기능이 요약되어 있습니다. 일반적으로 사용 중단에 대한 정보는 기능 릴리스의 일부일 뿐입니다.

사용 중단에 대한 릴리스 정보 작성

사용 중단에 대한 릴리스 정보는 다음 질문에 답변합니다.

  1. 이 기존 기능이 내 역할 또는 액세스 권한에 적용되나요?
  2. 더 이상 사용되지 않는 기능은 무엇인가요?
  3. 해당하는 경우 사용되지 않는 기능을 무엇이 대체하였나요?
  4. 해당하는 경우 어디에서 더 자세히 확인할 수 있나요?

대상 그룹(1) 사용되지 않는 기능에 대한 설명(2) 대체 기능(3) 자세한 내용은 문서 제목을 참조하세요(4).

  • 정보는 현재 시제로 작성하거나 예정된 변경에 대해서는 미래 시제로 작성합니다. 해당하는 경우 사용 중단이 발생할 예정된 릴리스를 지정합니다.
  • 반복과 불필요한 단어를 줄이기 위해 "지금"은 일반적으로 생략합니다.
  • 행위자와 영향을 명확히 하기 위해 가능한 경우 수동 언어를 사용하지 마세요.
  • 기능 제목 아래의 섹션에서 각 기능을 분류합니다.

사용 중단에 대한 릴리스 정보 예시

  • 예정된 사용 중단: GitHub Enterprise Server 3.8 이상에서는 인스턴스 보안을 보장하기 위해 관리 셸의 SSH 연결에서 안전하지 않은 알고리즘을 사용하지 않도록 설정됩니다.

  • 사용자가 끌어오기 요청 외의 커밋에 직접 추가하는 커밋 주석은 더 이상 끌어오기 요청 타임라인에 표시되지 않습니다. 사용자가 이러한 주석에 회신하거나 해당 주석을 해결할 수 없습니다. 타임라인 이벤트 REST API 및 GraphQL API의 PullRequest 개체도 더 이상 커밋 주석을 반환하지 않습니다

오류

오류는 릴리스 정보 또는 릴리스 설명서에서 이전에 게시된 부정확한 정보를 수정합니다.

오류 작성

오류는 다음 질문에 답변합니다.

  1. 해당하는 경우 GitHub Docs에 대한 릴리스 정보 또는 콘텐츠의 어떤 섹션이 영향을 받았나요?
  2. 잘못된 정보가 내 역할 또는 액세스 권한에 적용되었나요?
  3. 릴리스 정보 또는 설명서에서 잘못된 내용이 무엇인지 설명했나요?
  4. 오류는 언제 게시되었나요?

콘텐츠 (1)가 대상 그룹 (2)이 부정확한 정보를 요약 (3) 할 수 있다고 잘못 표시했습니다. [업데이트: 게시 날짜 4]

오류 예시

  • 기능이 GitHub Advisory Database의 사용자가 Elixir, Erlang의 Hex 패키지 관리자 등에 대한 권고를 볼 수 있다고 잘못 표시했습니다. 이 기능은 GitHub Enterprise Server 3.7에서 사용할 수 없으며 이후 릴리스에서 사용할 수 있습니다. [업데이트 날짜: 2023-06-01]

릴리스 정보 추가 또는 업데이트

메모를 추가하거나 변경했음을 사용자에게 알리거나 오류 게시 날짜를 표시하려면 "[업데이트 날짜: YYYY-MM-DD]" 형식으로 날짜 스탬프를 추가합니다.

릴리스 정보 제거

릴리스 정보를 제거했음을 알리려면 제거한 정보와 (해당하는 경우) 제거된 정보가 실제로 관련된 버전을 자세히 설명하는 "Errata" 섹션을 추가합니다. 정오표 작성을 참조하세요.

재사용 가능 문자열 및 변수

개별 명사(예: 제품 이름) 또는 완전한 문장이나 단락에 재사용 가능한 문자열을 사용합니다. 문장 조각과 구는 콘텐츠를 현지화할 때 문제를 일으킬 수 있으므로 재사용 가능한 문자열에 포함해서는 안 됩니다. 자세한 내용은 github/docs 리포지토리의 데이터 디렉토리,재사용할 수 있는 콘텐츠 만들기, 이 문서의 제품 이름 섹션을 참조하세요.

부분 TOC

문서의 섹션에 콘텐츠를 더 나누기 위해 H3 또는 H4 헤더가 사용되거나 일부 콘텐츠만 사용자와 관련된 경우 부분 TOC(목차)를 사용하여 사용자가 가장 관련 있는 정보를 식별하고 탐색하도록 도울 수 있습니다. 예를 들어 엔터프라이즈에 대한 감사 로그 스트리밍에서 사용자는 한 공급자에 대해서만 감사 로그 스트리밍을 설정하므로 “감사 로그 스트리밍 설정”의 부분 TOC를 사용하면 전체 섹션을 읽지 않고도 공급자를 선택하여 관련 콘텐츠로 이동할 수 있습니다.

H3 또는 H4 헤더를 콘텐츠를 그룹화하기 위해서만 사용하고 모든 정보가 사용자와 관련이 있을 수 있는 경우 부분 TOC를 추가하지 마세요. 예를 들어 ID 및 액세스 관리 정보에서 사람들은 해당 엔터프라이즈와 관련된 각 섹션을 읽고 고려해야 합니다. 사용자가 섹션을 선택하는 것이 아니라 각 섹션 전반을 읽어야 하므로 이 문서에 부분 TOC를 포함하지 않습니다. 부분 TOC를 추가하면 화면 읽기 프로그램 또는 기타 보조 기술을 사용하는 사람들이 필요한 내용을 찾기 전까지 강제로 더 많은 헤더를 탭하고 스크롤해야 합니다.

부분 TOC 서식을 목록으로 지정합니다. 모든 하위 구역을 문서에 표시되는 순서대로 포함하고 전체 머리글 제목을 사용하여 참조합니다.

부분 목차는 어떻게 콘텐츠가 구성되어 있는지 이해를 돕고 사용자와 가장 관련 있는 섹션을 선택하는 데 도움이 되는 문장 또는 단락이어야 합니다. 헤더 바로 아래에 부분 TOC를 포함하지 마세요.

부분 TOC의 예시

## Setting up the application

Set up your application according to your operating system.

* [Setting up for macOS](#setting-up-for-macOS)
* [Setting up for Windows](#setting-up-for-windows)
* [Setting up for Linux](#setting-up-for-linux)

### Setting up for macOS

TEXT

### Setting up for Windows

The application is supported for all versions of Windows, but the set up steps differ.

* [Windows 98](#windows-98)
* [Windows Vista](#windows-vista)
* [Windows 11](#windows-11)

#### Windows 98

TEXT

#### Windows Vista

TEXT

#### Windows 11

TEXT

### Setting up for Linux

TEXT

테이블

Markdown을 사용하여 GitHub Docs에 테이블을 추가합니다. 테이블은 읽고 유지 관리하기 어려울 수 있으므로 테이블을 만들기 전에 테이블의 데이터가 목록과 같은 다른 형식이 아니라 테이블 형식으로 가장 잘 표현되는지 확인해야 합니다. 테이블의 모든 행은 | 파이프로 시작하고 끝나야 합니다.

테이블 형식 정보를 표시할 때만 테이블을 사용합니다.

테이블은 비교해야 하는 정보 또는 여러 특성이 있는 값과 같은 테이블 형식 데이터를 표시하는 데 가장 적합합니다. 간단한 목록에는 테이블을 사용하지 마세요. 이 문서의 목록 섹션을 참조하세요.

테이블 데이터 설명하지 않기

테이블의 데이터와 해당 데이터가 중요한 이유는 앞의 내용, 열 헤더 그리고 필요한 경우 행 헤더에서 명확히 해야 합니다. 테이블의 데이터에 대한 불필요한 설명을 피합니다. 긴 설명이 없으면 테이블의 데이터가 명확하지 않은 경우 테이블에 행 헤더가 필요한지 또는 정보가 다른 방식으로 더 잘 전달될 수 있는지를 고려합니다.

예를 들어 자체 호스트형 실행기로 자동 스케일링에서는 지원되는 두 자동 스케일링 솔루션 간의 기능을 비교하는 테이블이 Each solution has certain specifics that may be important to consider.과 같은 문장과 함께 있습니다. 이 문서에서는 해당 정보가 표에서 명확하게 전달되기 때문에 비교되는 다른 기능을 설명하지 않습니다.

  • 올바른 사용: "GHES 버전에 따라 리포지토리별로 다른 크기 제한이 적용됩니다."
  • 잘못된 사용: "테이블의 첫 번째 행에는 GitHub Enterprise Cloud에 대한 정보가 표시됩니다. 두 번째 행에는 GitHub Enterprise Server에 대한 정보가 표시됩니다."
  • 잘못된 사용: "아래 표에서는 내보낸 마이그레이션 데이터의 종류를 보여 줍니다."

행 및 열 헤더에 적절한 마크업 사용

첫 번째 열이 데이터 값을 설명하는 테이블 (데이터 값은 아님)에는 행 헤더를 마크업해야 합니다. 이러한 표시는 보조 기술이 셀 간의 관계를 이해하는 데 중요합니다.

예를 들어 다음 테이블에서 테이블의 "예" 및 "아니요" 값을 이해하려면 열 헤더(역할)와 행 헤더(권한)를 모두 알아야 합니다.

조직 권한 소유자 멤버 중재자 청구 관리자 보안 관리자
리포지토리 만들기 예 예 예 아니요 예
청구 정보 보기 및 편집 예 아니요 아니요 예 아니요
조직에 참가할 사용자 초대 예 아니요 아니요 아니요 아니요

Markdown 테이블에 대한 행 헤더를 추가하려면 테이블을 Liquid 태그 {% rowheaders %} {% endrowheaders %}(으)로 래핑합니다. 행 헤더 사용에 대한 자세한 내용은 GitHub Docs에서 Markdown 및 Liquid 사용하는 방법을(를) 참조하세요.

모든 셀에 값 포함

테이블의 모든 셀에는 값이 있어야 합니다.

데이터가 없는 셀의 경우 "없음" 또는 "해당 없음"을 사용합니다. "NA" 또는 "N/A"를 사용하지 마세요.

행 머리글이 있는 테이블의 경우 첫 번째 셀(셀 "A1")은 사용자가 전체 표를 이해할 수 있도록 행 머리글을 설명해야 합니다. 그러나 이렇게 하면 표가 덜 명확해지거나 중복 정보가 추가되면 이 셀을 비워 둘 수 있습니다. 예를 들어 PowerShell 빌드 및 테스트 문서에서 첫 번째 셀은 “Modules”로 레이블을 지정할 수 있지만 각 행 머리글에 이미 “module”이라는 단어가 포함되어 있으므로 이 헤더는 표 전체를 이해하기 위해 설명 값을 추가하지 않는 정보를 반복합니다.

명확하고 일관된 기호 및 레이블 사용

기호를 사용하는 테이블의 경우:

  • 모든 셀을 채웁니다. 예를 들어 사용 권한 테이블에서 사용 권한이 필요한 항목의 셀만 값을 표시하지 마세요.
  • 옥티콘 또는 SVG를 사용합니다. 이모지는 사용하지 마세요. 옥티콘에 대한 자세한 내용은 GitHub Docs에서 Markdown 및 Liquid 사용하는 방법을(를) 참조하세요.
  • 긍정 값에 대해 확인 표시("예", "필수", "지원됨")를 사용하고 음수 값에 대해 X자 표시("아니요", "선택 사항", "지원되지 않음")를 사용합니다.
  • 시각적 특성이 아니라 기호의 의미를 설명하는 데 aria-label을(를) 사용합니다. 예를 들어 "확인 표시 아이콘"이 아니라 "필수"를 사용합니다.

테이블 데이터가 실제로 이진이 아닌 경우(예를 들어 모든 값이 "예" 또는 "아니요") 기호 외에 또는 기호 대신 텍스트 값이 필요할 수 있습니다. 예를 들어 GitHub 지원 정보 페이지에서 일부 기능은 “구매할 수 있음”으로 표시됩니다.

제한적인 각주 사용

각주를 참조하세요.

일관된 테이블 콘텐츠 정렬

가운데 맞춤해야 하는 옥티콘만 포함된 열을 제외하고 테이블의 모든 열은 왼쪽 맞춤이어야 합니다. 열에 텍스트와 옥티콘이 모두 포함된 경우 가운데 맞춤을 사용합니다.

테이블 콘텐츠는 기본적으로 왼쪽 맞춤입니다. 각 열의 맞춤을 지정하려면 Markdown 테이블 서식을 사용하여 헤더 행의 대시 오른쪽 또는 왼쪽에 콜론(:)을 사용합니다. 자세한 내용은 테이블로 구성 정보을(를) 참조하세요.

다음 예제는 Dependabot options reference의 테이블 일부입니다.

옵션 필수 보안 업데이트 버전 업데이트 설명
package-ecosystem 사용할 패키지 관리자
directory 패키지 매니페스트 위치
schedule.interval 업데이트 확인 빈도

해당 테이블은 다음의 맞춤 구문을 사용하여 생성됩니다.

| Option              | Required | Security Updates | Version Updates | Description                    |
|---------------------|:--------:|:----------------:|:---------------:|--------------------------------|
| `package-ecosystem` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Package manager to use         |
| `directory`         |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| Location of package manifests  |
| `schedule.interval` |{% octicon "check" aria-label="Supported" %}|{% octicon "x" aria-label="Not supported" %}|{% octicon "check" aria-label="Supported" %}| How often to check for updates |

Titles

제목에 문장 대/소문자를 사용합니다.

짧은 제목

짧은 제목으로 사이드바 탐색을 채웁니다. 짧은 제목은 사이드바 탐색에 표시되므로 컨텍스트를 사용하여 의미를 전달하고 전체 제목보다 약간 덜 정확할 수 있습니다. 짧은 제목의 목표는 사용자가 너무 긴 사이드바 탐색 항목 없이도 찾고 있는 콘텐츠를 찾을 수 있도록 돕는 것입니다. 짧은 제목은 문서의 맥락을 제공하여 이해를 돕고 다음 표준에 부합합니다.

  • 짧은 제목은 2~3단어로 구성됩니다.
    • 범주의 경우 짧은 제목은 27자 미만이어야 합니다.
    • 지도 항목의 경우 짧은 제목은 30자 미만이어야 합니다.
    • 문서의 경우 짧은 제목은 31자 미만이어야 하며 이상적으로는 20~25자 사이여야 합니다.
  • 짧은 제목은 동명사 대신 동사의 기본형을 사용합니다.
    • 올바른 사용: "알림 구성하기" 대신 "알림 구성"
  • 범주, 지도 항목 및 문서에 대한 짧은 제목에서는 제품 및 기능 이름이 어떤 제품 또는 기능과 관련이 있는지 명확히 알 수 있는 경우 제품 및 기능 이름을 생략할 수 있습니다.
  • 짧은 제목에는 전체 제목에 없는 새 단어를 사용하지 않습니다.
  • 짧은 제목은 비슷한 콘텐츠의 짧은 제목과 유사하게 작성합니다.
    • 올바른 사용: "조직 및 팀"과 "엔터프라이즈 계정"
    • 잘못된 사용: "조직 및 팀"과 "엔터프라이즈 계정 관리하기"

짧은 제목을 쓰는 것은 어려울 수 있습니다. 문자 수에 맞춰 짧은 제목을 작성하는 데 도움이 되도록 맥락을 고려합니다. 가능한 경우 반복되는 단어와 콘텐츠가 속한 지도 항목이나 범주의 제품 또는 기능 이름을 제거합니다.

사이트 정책 콘텐츠

사이트 정책 콘텐츠에 재사용 가능한 항목 또는 변수를 사용하지 마세요. 사이트 정책 문서는 법적 문서이며 사람이 읽을 수 있는 원본이 있어야 합니다.

그렇지 않으면 사이트 정책 콘텐츠는 GitHub Docs의 나머지 부분과 동일한 스타일과 콘텐츠 모델을 사용합니다.

사용자 인터페이스 요소

볼드체

볼드체를 사용하여 상호 작용할 수 있는 UI 요소를 설명합니다.

  • 왼쪽 사이드바에서 청구를 클릭합니다.
  • 끌어오기 요청의 대화 탭 아래쪽에 있는 병합 상자를 찾습니다.
  • 제목 옆에 새 키에 대한 설명 레이블을 추가합니다.

분기 이름

분기 이름에 코드 서식을 사용합니다.

  • main
  • USERNAME.github.io

버튼

단추 이름 서식을 볼드체로 지정하고 가능하면 "단추"라는 단어를 생략합니다. 단추를 사용하는 방법을 설명하려면 누른다고 하지 않고 "클릭"을 씁니다.

  • 올바른 사용: 끌어오기 요청을 클릭합니다.
  • 잘못된 사용: 끌어오기 요청 단추를 누릅니다.

확인란

확인란 이름 서식을 볼드체로 지정하고 "확인란"이라는 단어를 생략합니다. 확인란을 선택하거나 선택 해제하는 방법을 설명할 때 "선택" 또는 "선택 취소"를 사용합니다.

  • 올바른 사용: 모든 새 리포지토리에 대해 사용을 선택합니다.
  • 잘못된 사용: "모든 새 리포지토리에 사용" 확인란을 확인합니다.

동적 텍스트

사용자 인터페이스에서 변경되거나 사용자가 명령 또는 코드 조각에서 제공해야 하는 텍스트를 대문자로 나타냅니다.

  • 올바른 사용: 리포지토리 이름에 사용자 이름 추가를 클릭합니다.

목록 및 목록 항목

목록 및 클릭할 수 있는 목록 항목의 서식을 볼드체로 지정합니다. 목록 이름이 단어인지 옥티콘인지와 관계없이 드롭다운 메뉴나 확장되는 UI 요소와 같이 목록으로 된 상호작용을 설명하려면 "선택"을 씁니다. 목록 항목 선택을 설명하려면 "클릭"을 씁니다.

  • 올바른 사용: 백업 이메일 주소 드롭다운 메뉴를 선택하고 기본 이메일만 허용을 클릭합니다.
  • 잘못된 사용: "백업 이메일 주소” 드롭다운 메뉴를 클릭하고 기본 이메일만 허용을 클릭합니다.

위치

표준 용어를 사용하여 사용자 인터페이스 요소의 위치를 설명합니다.

  • 아래 또는 위
  • 옆
  • 왼쪽 위, 오른쪽 위, 왼쪽 아래, 오른쪽 아래
  • 페이지 상단, 페이지 하단, 페이지 오른쪽, 페이지 왼쪽

패널

가능하면 패널을 언급하지 마세요. 대신 무엇을 해야 하는지 설명합니다.

  • 올바른 사용: 리포지토리의 차트 및 그래프 보기를 클릭한 다음 드롭다운 메뉴에서 보려는 기간을 선택합니다.
  • 잘못된 사용: 차트 및 그래프 보기를 클릭하여 선택한 리포지토리의 패널을 연 다음 드롭다운 메뉴에서 보려는 기간을 선택합니다.

UI 변경 내용을 설명하거나 UI와 상호 작용하는 방법을 설명하기 위해 패널을 언급해야 하는 경우 패널 이름 서식을 사용자 인터페이스 텍스트로 지정합니다. 패널이라는 단어를 사용해서 의미가 더 명확해지거나 UI에 패널 이름이 없는 경우에만 패널이라는 단어를 포함합니다.

  • 올바른 사용: "보안 적용 범위" 패널에서 사용 또는 사용 안 함을 선택합니다.
  • 올바른 사용: 패널에서 사용 또는 사용 안 함을 선택합니다.

라디오 단추

라디오 단추 레이블 서식을 볼드체로 지정하고 "라디오 단추" 또는 다른 설명자를 생략합니다. 라디오 단추를 사용하는 방법을 설명하려면 "선택"을 사용합니다.

리포지토리 이름

백틱을 사용하여 고정 폭 글꼴로 리포지토리 이름의 스타일을 지정합니다. 사용자가 리포지토리로 이동할 것으로 예상되는 경우 리포지토리에 대한 링크를 제공합니다.

  • 올바른 사용: 자세한 내용은 github/docs 리포지토리를 참조하세요.

응답 요소

모호하거나 혼동되는 경우에만 UI 요소의 응답 상태를 문서화합니다. 응답성이 뛰어난 UI 요소로 인해 작업이 명확하지 않은 경우 작업의 목표를 달성하기 위해 누군가가 수행해야 하는 상호 작용을 설명합니다. UI 요소의 시각적 상태만 설명하지 마세요.

  • 사용: 보안 탭을 클릭합니다. 보안이 표시되지 않으면 ⋮ 기호를 클릭하여 리포지토리 메뉴를 확장합니다.

사용자 인터페이스 텍스트

사용자 인터페이스에서 텍스트를 참조할 때 텍스트를 정확하게 재현합니다. 상호 작용할 수 없는 UI 텍스트는 따옴표로 묶습니다.

  • 올바른 사용: "IP 허용 목록"에서 편집을 클릭합니다.

추가 리소스

Microsoft 스타일 가이드:

비디오

텍스트 기반 정보를 보강하기 위해 동영상을 추가할 수 있지만 동영상이 텍스트 콘텐츠를 대체해서는 안 됩니다. 동영상은 일부 사용자가 접근할 수 없으며 검색을 통해 찾기도 어렵습니다.

GitHub Docs 웹 사이트의 동영상은 잘 제작되고 장애가 있는 사용자에게 장벽을 낮춰야 하며 동영상의 콘텐츠 모델을 준수해야 합니다. 자세한 내용은 GitHub Docs에서 비디오를 사용하는 방법을 참조하세요.

음성 및 톤

다양한 사용자가 쉽게 접근할 수 있는 명확하고 간단한 언어를 사용합니다. 진정성을 갖고 공감하며 자신감 있게 씁니다.

대상 그룹을 위해 작성: 일부 전문 용어 및 기술 용어가 필요하지만 모든 사용자가 동일한 수준의 기술 전문 지식을 가지고 있다고 가정하지 마세요.

가능하면 능동태를 사용합니다. 수동태는 동작의 개체를 강조해야 할 때 허용됩니다.

우리는 글로벌 개발자 커뮤니티입니다. 특정 지역이나 국가와 관련된 구문 표현, 관용구 및 속어는 사용하지 마세요.

접근 가능한 콘텐츠 작성에 대한 자세한 내용은 "Microsoft의 브랜드 음성: 무엇보다도 단순하고 인간적인 것" 및 "Microsoft 스타일 및 음성을 위한 상위 10가지 팁"을 참조하세요.

단어 선택 및 용어

일반적인 지침과 GitHub 관련 용어는 용어집을 참조하세요. 자세한 지침은 Microsoft 스타일 가이드의 "A-Z 단어 목록"을 참조하세요.

약어

제품 자체에서 명시적으로 단축된 단어를 참조하는 경우를 제외하고는 단어를 전부 표기합니다.

  • 올바른 사용: 리포지토리
  • 잘못된 사용: 리포
  • 올바른 사용: 관리자, 관리자 권한이 있는 사용자
  • 잘못된 사용: 관리자

GitHub의 사용자 인터페이스에서 사용되지 않는 기호 또는 옥티콘을 사용하지 마세요.

  • 올바른 사용: 파일을 클릭한 다음 편집을 클릭합니다.
  • 잘못된 사용: 파일 > 편집을 클릭합니다.

계정

제품 이름 및 계정

애매함과 혼동을 방지하려면 제품 이름을 형용사로 사용하여 제품의 계정을 설명하지 마세요. 대신 계정 유형을 명확히 하고 계정 및 제품이 결합하는 것을 방지하는 보다 명확한 구문을 선택합니다. 계정을 언급할 때는 제품 간에 명확하게 구분해야 하는 경우에만 제품 이름을 참조하세요. GitHub 제품에서 사용할 수 있는 계정 유형에 대한 자세한 내용은 Types of GitHub accounts(GitHub 계정 유형)을(를) 참조하세요.

  • 올바른 사용: GitHub Enterprise Cloud의 조직
  • 잘못된 사용: GitHub Enterprise Cloud 계정
  • 잘못된 사용: GitHub Enterprise Server 조직
  • 올바른 사용: 기여 횟수를 GitHub.com 프로필로 보내 GitHub Enterprise Server 작업을 강조할 수 있습니다.

GitHub의 개별 계정

상황에 따라 개별 사용자가 다양한 방식으로 로그인하는 계정을 말합니다.

콘텐츠가 엔터프라이즈 제품 관리에 관한 것이 아니라면 GitHub의 개별 사용자 계정을 "개인 계정"으로 설명합니다. 이렇게 하면 UI와 일관성이 생기고 동일한 것을 의미하는 두 개의 용어로 사용자를 혼동시키는 것을 방지합니다.

  • 올바른 사용: 개인 계정에 대한 예정된 알림 관리
  • 잘못된 사용: 사용자 계정에 대한 예정된 알림 관리

엔터프라이즈 제품 계정

관리자는 GitHub의 엔터프라이즈 제품을 사용하여 엔터프라이즈 계정을 관리합니다. 엔터프라이즈 계정은 여러 조직을 소유할 수 있으며 사용자의 사용자 계정은 조직의 구성원일 수 있습니다. 자세한 내용은 각 제품의 “엔터프라이즈의 역할” 문서를 참조하세요.

사용자가 엔터프라이즈 계정으로 관리하는 다른 사용자의 계정을 설명하는 경우 "사용자 계정"을 사용합니다. 이러한 방법은 다음 제품에 적용됩니다.

  • Enterprise Managed Users이(가) 있는 GitHub Enterprise Cloud
    • 올바른 사용: Enterprise Managed Users에서 엔터프라이즈 구성원의 사용자 계정을 만들고 관리할 수 있습니다.
    • 잘못된 사용: Enterprise Managed Users에서 엔터프라이즈 구성원의 개인 계정을 만들고 관리할 수 있습니다.
  • GitHub Enterprise Server
    • 올바른 사용: 사용자 계정을 임시로 인수해야 하는 경우...
    • 잘못된 사용: 개인 계정을 임시로 인수해야 하는 경우...

다음 설명서는 "사용자 계정"을 참조해야 합니다.

Enterprise Managed Users을(를) 사용하지 않는 GitHub Enterprise Cloud의 엔터프라이즈는 소유한 조직 멤버를 설명할 때 "개인 계정"을 사용합니다.

  • 올바른 사용: SAML SSO를 구성하는 경우 조직 멤버는 GitHub.com에서 개인 계정에 계속 로그인합니다.
  • 잘못된 사용: SAML SSO를 구성하는 경우 조직 멤버는 GitHub.com에서 사용자 계정에 계속 로그인합니다.

Enterprise Managed Users가 없는 GitHub Enterprise Cloud를 설명하는 설명서는 일반적으로 조직에 대한 SAML Single Sign-On 관리 카테고리에 있습니다.

다른 서비스에 대한 계정

통합 또는 인증 공급자와 같이 GitHub 이외의 서비스에 대한 계정을 설명할 때는 "사용자 계정"을 사용합니다.

머리글자어

제목이나 헤더를 제외하고 문서에서 처음 사용되는 두문자어는 풀어 씁니다.

앱

일반 콘텐츠에서는 "앱" 또는 "애플리케이션"을 사용합니다.

  • 올바른 사용: GitHub Marketplace에 앱 게시 및 나열

제품이 아니므로 OAuth apps을(를) 지시할 때 "App"을 사용합니다.

  • 올바른 사용: OAuth app 등록
  • 잘못된 사용: OAuth App 등록

제품이므로 GitHub Apps을(를) 지시할 때 "App"을 사용합니다.

  • 올바른 사용: GitHub App 등록

GitHub Apps 및 OAuth apps은(는) 앱 등록과 앱이 작동하도록 만드는 코드로 구성된 두 부분으로 구성됩니다.

  • GitHub UI의 GitHub App 설정/구성만 참조하려면 "등록" 및 "GitHub App 등록"과 같은 용어를 사용합니다.

    • 올바른 사용: GitHub App 등록
    • 올바른 사용: GitHub App 등록 업데이트
    • 잘못된 사용: GitHub App 생성
    • 잘못된 사용: GitHub App 수정

  • 앱의 코드만 의미하는 경우 "앱 코드"와 같은 용어를 사용합니다.

    • 올바른 사용: 앱의 코드
    • 올바른 사용: GitHub App의 코드
    • 올바른 사용: 앱 코드
    • 잘못된 사용: GitHub App
    • 잘못된 사용: OAuth app

  • 전체 앱(등록 + 코드)을 의미하는 경우 GitHub App 또는 OAuth app(으)로 표시합니다.

GitHub Apps은(는) 조직 및 사용자 계정에 설치가 가능합니다. 앱 설치를 의미하는 경우 "GitHub App" 대신 "GitHub App 설치"를 사용합니다.

통화

달러, 센트, 통화 금액 또는 $ 기호를 사용할 때 금액이 0인 경우에도 사용된 통화가 정의되어 있는지 확인합니다. 가능한 ISO 표준 통화 이름 및 ISO 표준 통화 코드를 사용합니다.

통화 이름에는 소문자를 사용하지만 국가 또는 지역은 대문자로 표시합니다.

  • 올바른 사용: US dollar.
  • 잘못된 사용: US Dollar, $USD dollar.

통화 코드에 대문자를 사용합니다.

  • 올바른 사용: USD.

문서에 참조가 하나만 있는 경우 금액 앞에 $ 기호 없이 통화 이름을 사용합니다.

  • 올바른 사용: 10 US dollars은(는) 통화에 대한 단일 참조입니다.

문서에 동일한 통화에 대한 여러 참조가 포함된 경우 첫 번째 참조가 금액 앞에 $ 기호 없이 통화 이름을 사용하고 통화 이름 뒤에 오는 괄호로 통화 코드를 묶어야 합니다.

문서에서 통화를 그 다음 참조할 때 또는 적절한 경우(예: 공간을 고려하는 경우 또는 테이블 또는 목록에 여러 금액이 표시되는 경우) 금액 앞에 $ 기호를 포함하고 ISO 표준 통화 코드를 금액 다음에 사용합니다.

  • 올바른 사용: 처음 참조하는 경우 10 US dollars (USD) 및 후속 참조에 $0.25 USD을(를) 사용합니다.
  • 잘못된 사용: $10 US dollars (USD), USD$0.25.

첫 번째 참조가 센트 또는 달러 금액이 아닌 경우 첫 번째 참조 직후에 괄호를 사용하여 통화가 사용되는 국가 또는 지역을 대문자로 표시합니다. 이후에 통화 참조는 위의 지침을 사용하여 처리합니다.

  • 올바른 사용: 처음 참조하는 경우 99 cents (US currency) 및 후속 참조에 99 cents을(를) 사용합니다.
  • 잘못된 사용: $0.99 (US currency), $0.99 USD cents, USD$0.99 cents.

사용 권한

권한은 특정 작업을 수행할 수 있는 기능입니다. 예를 들어 문제를 삭제하는 기능이 권한입니다.

역할은 사용자에게 할당될 수 있는 사용 권한의 집합입니다. 역할은 여러 수준에 있습니다.

  • 계정(예: 조직 소유자, 엔터프라이즈 계정 청구 관리자)
  • 리소스(예: 리포지토리의 쓰기, 보안 권고의 관리)
  • 팀(예: 팀 유지 관리자)

사용자의 액세스는 일반적으로 해당 능력이 어떤 역할이나 개별 권한에서 나오는지에 관계없이 특정 상황에서 사용자가 갖는 모든 능력을 나타냅니다.

둘 사이의 구분이 중요한 경우에만 사용 권한 또는 역할을 사용합니다. 그렇지 않으면 액세스를 사용합니다.

  • 올바른 사용: 사용자 지정 리포지토리 역할을 생성하려면 상속된 역할을 선택하고 개별 권한을 추가합니다.
  • 올바른 사용: 조직 리포지토리에 대한 팀 액세스 관리
  • 올바른 사용: 팀 멤버십이 조직 소유자 역할과 다른 수준의 액세스 권한을 제공하는 경우...
  • 올바른 사용: 쓰기 권한이 있는 사람...
  • 잘못된 사용: 쓰기 역할의 사람은 다음을 수행할 수 있습니다.
  • 잘못된 사용: 쓰기 역할의 사람...
  • 잘못된 사용: 쓰기 권한이 있는 사람...
  • 잘못된 사용: 쓰기 권한이 있는 사람...

작업을 수행하는 데 필요한 액세스를 지정할 때 작업과 동일한 수준의 역할만 참조합니다. 예를 들어 보호된 분기를 구성하려면 리포지토리 수준 역할인 리포지토리에 대한 관리자 액세스 권한이 필요합니다. 조직 수준 역할인 조직 소유자가 되어 리포지토리에 대한 관리자 액세스 권한를 얻을 수 있지만 리포지토리 수준 역할이 실제로 작업을 수행하는 기능을 제어하므로 리포지토리 수준 역할만 언급합니다.

  • 올바른 사용: 리포지토리에 대한 쓰기 권한이 있는 사람이 리포지토리에 대해 X 작업을 수행합니다.
  • 잘못된 사용: 조직 소유자 및 쓰기 권한이 있는 사용자가 리포지토리에 대해 X 작업을 수행합니다.

사용 권한 설명을 위한 단어 선택에 대한 자세한 내용은 콘텐츠 모델에서 GitHub Docs 문서의 내용을(를) 참조하세요.

전치사

수정한 문장이 어색하거나 너무 딱딱하지 않다면 전치사로 문장을 끝내지 마세요.

제품 이름

이 가이드의 "제품 이름" 구역을 참조하세요.

사용하거나 사용하지 말아야 할 용어

사용할 용어사용하지 말아야 할 용어
사람사용자, 고객
terminal셸
사용자 이름login
sign inlog in, login
등록(sign up)등록(signup)
권장 한계soft limit
emaile-mail
프런트 매터프런트 매터, 프런트 매터
GitHub에서원격 리포지토리에서
키를 누르세요키를 치거나 두드리세요
(사용자 인터페이스에서) 타자를 치세요(사용자 인터페이스에서) 입력하세요
(명령줄에서) 입력하세요(명령줄에서) 타자를 치세요

단어 선택

모호한 동사

작업이 필요하거나 한 옵션이 다른 옵션보다 선호되는 경우 "may," "might," "ought," "should," "could," "would," "can"과 같은 모호한 모달 보조 동사를 사용하지 마세요. 이러한 동사는 명령 또는 제안으로 해석될 수 있습니다. 대신 작업이 필수인지 아니면 선택 사항인지를 명확하게 나타내는 동사를 사용합니다. 옵션 또는 제안 사항인 경우 해당 작업이 선택 사항임을 분명히 하는 때에만 이러한 동사를 사용할 수 있습니다.

  • 올바른 사용: 사용할 바로 가기 키를 결정할 수 있습니다.
  • 올바른 사용: git clone 명령을 사용하여 리포지토리를 복제합니다.
  • 잘못된 사용: git clone 명령을 사용하여 리포지토리를 복제할 수 있습니다.
  • 잘못된 사용: 분기를 삭제할 수 있습니다.

보이지 않는 복수 표현

단수 또는 복수로 해석될 수 있어 의미가 모호한 단어인 보이지 않는 복수를 피합니다. 예를 들어 "파일 검색"은 단일 파일 또는 여러 파일의 검색을 의미할 수 있습니다.

  • 올바른 사용: 파일을 검색한 후 저장할 위치를 선택합니다.
  • 잘못된 사용: 파일 검색 후 저장할 위치를 선택합니다.

명사화

동사 또는 형용사에서 명사화된 명사를 사용하지 않습니다. 명사화는 문장을 더 길게 만들어 이해하고 번역하기가 더 어려워질 수 있습니다.

  • 올바른 사용: 워크플로가 완료되면 패키지가 표시됩니다.
  • 잘못된 사용: 워크플로가 완료에 도달하면 패키지가 표시됩니다.

명사 문자열

번역에서 수식하는 단어를 알 수 없기 때문에 잘못된 번역으로 이어질 수 있는 누적 한정자(명사 문자열)를 사용하지 마세요. 전치사로 명사 문자열을 바꿀 수 있습니다. 누적 한정자를 꼭 사용해야 하는 경우 사용자와 번역가가 무엇이 수식되는지 이해할 수 있도록 배경 정보와 컨텍스트가 명확해야 합니다.

  • 올바른 사용: 공용 리포지토리의 기본 소스 설정
  • 잘못된 사용: 공용 리포지토리 기본 소스 설정

모호한 명사 및 대명사

대명사가 둘 이상의 선행을 참조하는 것처럼 보이는 경우 선행을 명확하게 하기 위해 문장을 다시 입력하거나 명사를 명사로 바꿔 모호성을 제거합니다.

  • 올바른 사용: 분기에 대한 최종 커밋을 수행하고 끌어오기 요청을 병합한 후 분기를 삭제할 수 있습니다.
  • 잘못된 사용: 분기에 대한 최종 커밋을 수행하고 끌어오기 요청을 병합한 후 그것을 삭제할 수 있습니다.

Footnotes

  1. Not to be confused with Davy Jones of The Monkees ↩

  2. Also humans ↩