GitHub Docs에서 비디오 사용하기

이 가이드에서는 GitHub Docs에 대한 사용자 요구를 지원하는 비디오를 만드는 방법을 설명합니다.

이 문서의 내용

GitHub Docs에 관한 비디오

비디오는 GitHub Docs에서 거의 사용되지 않습니다. 문서에 가장 적합한 사용자 환경을 제공하기 위해 비디오가 필요한 경우, 작성된 텍스트와 함께 사용됩니다. 비디오는 문서 콘텐츠를 대체하지 않습니다. 비디오는 정보를 전달하는 유일한 방법이 되어서는 안되는데 이는 최신 정보를 유지하기가 더 어렵고 모든 사람이 액세스할 수 없기 때문입니다.

다음 지침을 사용하여 Docs의 문서 또는 방문 페이지에 비디오를 포함하기 적합한지를 확인합니다.

비디오 링크를 추가하거나 GitHub Docs에 비디오를 포함하는 경우 github/docs 리포지토리의 GitHub Docs 비디오 파일에 비디오의 메타데이터를 추가합니다.

Docs 팀은 비디오 콘텐츠를 만들거나 유지하지 않습니다. 비디오는 순수하게 보조적인 것으로 중요하거나 복잡한 주제를 전달하는 데 도움을 주고, Docs 팀이 소유한 콘텐츠 형식이 아니므로 드물게 사용해야 합니다.

비디오 검사 목록

이 검사 목록을 사용하여 동영상이 문서 또는 방문 페이지에 추가하는 데 적합한지 빠르게 확인할 수 있습니다.

  • 비디오가 정보를 전달하는 유일한 방법인가요?
  • GitHub이(가) 비디오를 소유하고 있나요?
  • 비디오가 잘 제작되었나요? (자세한 내용은 모범 사례 섹션을 참조하세요.)
  • 비디오에 가장 광범위한 사용자 그룹이 액세스할 수 있나요? (자세한 내용은 접근성 요구 사항 섹션을 참조하세요.)
  • 비디오 길이는 오 분 미만인가요?
  • 비디오가 Docs에 특정 대상 그룹 및 목적이 있나요? 특정 제품 또는 기능에만 관련된 경우 버전을 지정해야 합니다. 자세한 내용은 버전 관리 섹션을 참조하세요.

이러한 항목에 "아니요"라고 대답하는 경우 비디오는 GitHub Docs에 추가하는 데 적합하지 않습니다.

비디오 관리하기

비디오에 유지 관리 일정이 있거나 콘텐츠가 만료된 경우 콘텐츠 감사 및 업데이트를 직접 담당하는 팀이 있는 경우, 추가 단계 없이 비디오를 포함할 수 있습니다.

비디오에 유지 관리 일정이 없는 경우, 적절한 대상 날짜에 이슈를 생성하여 비디오를 검토하거나 제거합니다.

모범 사례

이러한 모범 사례를 사용하여 비디오가 잘 제작되었는지 그리고 GitHub Docs에 포함할 수 있을 만큼 높은 품질인지를 확인할 수 있습니다.

좋은 비디오는 단계와 목표를 포함하는 교육적인 안건을 소개하여 시청하는 사람이 학습할 내용을 빠르게 알 수 있도록 합니다. 비디오는 시연적으로 수행하는 관련 단계를 표시하고 설명합니다. 비디오는 관심을 끌고 고무적이어야 합니다. 비디오는 GitHub Docs에 포함되도록 잘 제작되어야 합니다. 잘 제작된 비디오에는 장애가 있는 사용자를 위한 장벽이 거의 없으며, 전문적인 내레이션(내레이션된 비디오인 경우)이 있고, 명확한 시각적 개체가 있으며, GitHub 또는 Microsoft와 같은 신뢰할 수 있는 원본에서 제공됩니다.

비디오는 크게 제품 개요, 기능 동영상 및 자습서의 세 가지 범주로 그룹화됩니다. 이러한 설명은 각 비디오 유형을 일반화한 것입니다. 일부 비디오는 한 범주에 완벽하게 맞지 않을 수 있지만 정확한 지침을 충족하지 않아도 여전히 유용할 수 있습니다.

제품 개요

  • 목적: 제품이 무엇인지 간략하게 설명하고, 기본 기능을 소개하며, 사람들이 관심을 가지게 합니다.
  • 길이: 일 분 미만
  • 가능한 대상 그룹: 기능이 목표에 유용한지 알고 싶은 사람, GitHub을(를) 접하는 사용자 및 제품이 수행하는 작업을 이해하려고 하는 사용자
  • Docs에서 가능한 위치: 방문 페이지 및 가이드

기능 동영상

  • 목적: 개념적 또는 절차적 콘텐츠 포함
  • 길이: 가능한 한 짧게, 오 분을 초과하지 않음. 긴 콘텐츠는 짧고 포커스가 있는 동영상 여러 개로 나누기
  • 가능한 대상 그룹: 기능이나 기능 사용 방법을 학습하는 사람
  • Docs에서 가능한 위치: 가이드, 개념 문서, 절차 문서

자습서

  • 목적: 초보 사용자가 제품을 사용하거나, 채택을 유도하거나, 복잡한 기능을 설명할 수 있도록 지원
  • 길이: 개별 비디오는 오 분 이내여야 합니다. 복잡한 주제는 문서 전체에 걸쳐 여러 개의 짧은 비디오 시리즈로 할 수 있습니다. 총 길이는 최대 15분이어야 합니다.
  • 가능한 대상 그룹: 기능 또는 제품 신규 사용자
  • 가능한 위치: 가이드

비디오를 사용하는 경우

스크린샷 또는 다이어그램과 같은 다른 시각적 개체 대신 움직임이나 상태 변화를 보여주는 게 중요할 때, 이를테면 한 화면에서 다른 화면으로 이동하거나 여러 메뉴를 통해 진행하는 기능을 시연하는 경우 비디오를 쓸 수 있습니다. 그러나 스크린샷 또는 텍스트가 이러한 절차를 설명하기에 충분할 수 있습니다.

또한 비디오는 기능이나 제품을 소개하는 데 도움이 될 수 있으며 30초짜리 비디오에 여러 단락으로 작성해야 하는 정보를 포함할 수 있습니다.

이러한 정보가 알려주는 절차 또는 개념의 가치를 설명하는 데 비디오를 사용하세요.

비디오를 사용하지 않는 경우

빠르게 변경되어서 비디오를 오래된 상태로 만들 수 있는 기능에 대해서는 비디오를 사용하지 마세요. 작성된 콘텐츠와 모순되거나 스타일 가이드의 어떤 부분이라도 위반하는 비디오는 사용하지 마세요. 절차를 설명하거나 상술하지 않고 그저 작업을 보여주기만 하는 비디오는 사용하지 마세요. 비디오는 유용하고 관련성이 있어야 하며, 시간이 지남에 따라 정확하게 유지되어야 합니다.

접근성 요구 사항

다음은 GitHub Docs에 비디오를 포함하기 위한 최소 요구 사항입니다. 비디오가 이러한 요구 사항을 위반하는 경우 Docs에 추가할 수 없습니다.

  • 깜박임 또는 섬광 효과 없음
  • 선택 자막이 있어야 합니다. 자세한 내용은 아래의 비디오 캡션 만들기를 참조하세요.
  • 그래픽이 자막 표시되는 위치와 겹치지 않음
  • 입력 체계는 알아볼 수 있어야 합니다.
  • 모든 오버레이에는 충분한 대비 비율이 있어야 합니다.
  • 모든 텍스트는 읽을 수 있을 만큼 긴 화면에 있어야 합니다(텍스트는 소리 내 두 번 읽는 데 걸리는 시간보다 더 오래 화면에 표시되어야 합니다).
  • 장면별로 일어나는 일에 대한 설명 대본을 교정해야 합니다. 자세한 내용은 아래의 비디오 대본 만들기를 참조하세요.
  • 비디오는 자동 재생되지 않습니다.

비디오 자막 만들기

비디오에는 Docs 사이트에 추가되기 전에 사람이 생성한 자막이 있어야 합니다. 자동 자막 기술을 사용하여 자막을 만들 수 있지만, 정확도를 위해 사람이 교정하고 편집해야 합니다. 비디오 호스팅 서비스에 YouTube와 같은 원시 자막 도구가 있는 경우 해당 도구를 사용하여 자막을 준비하거나 비디오와 함께 업로드할 적절한 형식 SRT 또는 VTT 대본 파일을 만들 수 있습니다.

자막 만들기는 더 많은 사람이 액세스할 수 있는 비디오를 제작하는 프로세스의 일부이므로 GitHub Docs에 추가되는 비디오의 소유자는 자막을 제공해야 합니다.

자막에 대한 지침

가능하다면 자막은 비디오에서 말한 단어와 정확히 일치해야 합니다. 심각한 시간 제약 조건으로 지정된 시간에 자막을 읽기가 어렵지 않는 한, 자막을 의역하거나 자르지 마십시오.

오디오와 거의 동시에 표시되도록 자막을 동기화해야 합니다. 캡션은 항상 스피커가 말하기 시작하는 순간에 화면에 표시되도록 시간을 지정해야 합니다. 빠른 음성의 경우 캡션 오디오에 정확하게 맞춰 읽기 어려울 경우 음성이 완료된 후 화면에 유지되도록 캡션 확장할 수 있습니다.

비디오에 여러 스피커가 있는 경우 캡션 스피커를 식별합니다. 문장이 시작되기 전에 화자의 이름 또는 설명이 포함된 이름(예: Developer)을 추가하여 이 작업을 수행합니다. 예: Jimmy: Hello.. 모든 대화 라인이 아니라 화자가 변경되는 경우에만 이 작업을 수행해야 합니다. 말하는 시각적 개체에서 분명한 경우 화자를 식별할 필요가 없습니다.

캡션은 한 줄 또는 두 줄이어야 하며 줄당 32자 이하여야 합니다. 각 새 문장을 새 줄에 배치합니다. 문장 중간에 줄을 끊어야 하는 경우 논리 지점, 예를 들어 and 또는 but처럼 쉼표 뒤 또는 연결 전에서 그렇게 합니다.

YouTube에서 자막 추가 및 편집

YouTube에서 호스트되는 비디오는 YouTube 문서에서 자막 및 캡션 추가 및 캡션 편집 또는 제거를 참조하세요.

비디오 대본 만들기

Docs에 연결되거나 포함된 모든 비디오에 대해, 비디오 설명 대본이 있어야 합니다. 대본 문서는 YAML 프런트 매터 및 Markdown 콘텐츠와 함께 다른 문서와 같이 형식이 지정됩니다. Docs 사이트에 대본을 추가하려면, content/video-transcripts에 문서를 만들고, 문서의 본문 텍스트로 대본을 포함합니다. 문서에 transcript-VIDEO-NAME.md과(와) 같이 파일 이름 및 Transcript - VIDEO NAME의 title 프런트 매터 속성을 지정하세요. video-transcripts 디렉터리의 index.md 파일에 문서를 추가하세요.

Liquid 변수 또는 재사용 가능 변수를 사용하여 대본에 제품 이름과 같은 항목을 대체하지 마세요. 대본은 비디오의 오디오에 충실해야 하며, 비디오가 생성된 후 변수나 재사용 가능한 항목을 업데이트트한 결과로 대본의 텍스트를 변경해서는 안 됩니다.

대본을 만드는 것은 더 많은 사람들이 액세스할 수 있는 비디오를 제작하는 과정의 일부이므로, Docs 사이트에 추가되는 비디오의 소유자는 대본에 대한 콘텐츠를 제공해야 합니다.

대본의 기초로 자막을 사용할 수 있습니다. 자막을 편집하여 타임스탬프를 제거하고 아래에 자세히 설명된 관련 정보를 포함하세요. 설명 대본은 비디오 콘텐츠를 이해하는 데 필요한 오디오 및 시각적 정보의 텍스트 버전을 포함합니다.

  • 비디오에 여러 화자가 있는 경우 대본에서 화자를 식별하세요.
  • 발표자의 성별을 알면 그 사람의 행동을 설명할 때 선호하는 대명사를 사용할 수 있습니다. She points to the computer screen.을 예로 들 수 있습니다. 발표자의 성별이 알려지지 않았거나 설명하고 있는 시각적 개체와 관련이 없는 경우 단칭 they 대명사를 사용할 수 있습니다.
  • 논리적 단락, 목록 및 섹션의 대본 서식을 지정하세요. 사용자가 콘텐츠를 이해하는 데 도움이 되는 경우 섹션에 머리글을 추가할 수 있습니다. 비디오를 보지 않아도 대본에서 정보를 얻는 방법을 고려하세요.
  • 자막에 포함되지 않은 화면 텍스트, 관련 시각적 요소 또는 음성이 아닌 소리를 추가하세요. 이러한 설명은 비디오에서 함께 제공되는 음성 텍스트 뒤에 두세요. 시각적 정보 서식은 대괄호로 지정하세요. 예들 들어 [Background music plays. The narrator clicks the Code button and then the "+ New codespace" button.]입니다.
  • 대본 문서의 YAML 프런트 매터에 product_video 속성을 추가합니다. product_video 속성 값은 비디오의 YouTube URL입니다. 동영상의 YouTube URL은 대본 문서에 외부 링크로 표시될 것입니다.
  • 대본의 끝에서 End of transcript.라고 쓰고 비디오가 패턴 For more information about PRODUCT, see the ["Product" documentation](link/to/landing-page).을(를) 사용하고 있는 제품의 방문 페이지에 연결하세요.

오디오 및 시각적 대본의 더 많은 예시는 W3C 문서의 시각적 개체 설명이 포함된 텍스트 대본을 참조하세요.

외부 호스팅 비디오의 대본에 연결하기

호스팅되는 플랫폼의 비디오 설명에 한 비디오의 대본이 포함된 문서 링크를 추가하세요. 자세한 내용은 YouTube 설명서의 비디오 설정 편집을 참조하세요.

내장된 비디오의 대본에 연결하기

내장된 비디오가 포함된 콘텐츠에서, YAML 프런트 매터의 product_video_transcript 속성을 product_video 속성 아래에 추가하세요. product_video_transcript 값은 video-transcripts 디렉터리의 대본 문서에 대한 링크입니다.

title: Example product landing page
product_video: 'https://www.youtube-nocookie.com/embed/URL'
product_video_transcript: /content/video-transcripts/TRANSCRIPT-TITLE

비디오 제목

제목은 서술적이어야 하며 콘텐츠 모델의 제목에 대한 지침을 따라야 합니다. 자세한 내용은 GitHub Docs 문서의 내용을(를) 참조하세요.

버전 관리

비디오가 특정 GitHub 제품(Free, Pro 및 Team, GitHub Enterprise Server 및 GitHub Enterprise Cloud) 전용인 경우, 비디오에는 해당 제품에 적합한 버전이 지정되어야 합니다. Liquid 조건문을 사용하여 비디오의 버전을 적절하게 지정하세요. 콘텐츠를 처음 만들 때 Liquid 조건부 버전 관리를 추가해야 하거나 기능 업데이트 또는 GitHub Enterprise 릴리스를 위해 콘텐츠를 업데이트할 때 추가해야 할 수도 있습니다. 액체 조건문 및 버전 관리에 대한 자세한 내용은 설명서 버전 관리하기을(를) 참조하세요.

비디오 호스팅하기

비디오는 GitHub이(가) 소유하고 있으며 Docs 팀에 액세스 권한을 부여할 수 있는 위치에서 호스팅되어야 합니다. 비디오는 사용자를 추적하거나 쿠키를 사용하면 안 됩니다. 현재 GitHub의 비디오는 YouTube에서 호스트되며 https://www.youtube.com/VIDEO에서 https://www.youtube-nocookie.com/VIDEO까지 내장된 URL에 대한 도메인을 변경하여 개인 정보 보호 강화 모드를 사용하는 Docs에 추가됩니다.