GitHub Docs에 대한 모범 사례

GitHub 설명서 정보

GitHub에서 정확하고, 가치 있고, 포괄적이며, 접근 가능하고, 사용하기 쉬운 설명서를 만들기 위해 노력하고 있습니다.

GitHub Docs에 기여하기 전에 잠시 시간을 내어 GitHub의 설명서 철학, 기본 사항, 콘텐츠 디자인 원칙을 숙지하세요.

새 문서를 만들거나 기존 문서를 업데이트하는 경우 GitHub Docs에 대해 작성할 때 다음 지침을 따라야 합니다.

시작하기 전에 작성 대상, 해당 목표, 문서에서 다룰 핵심 작업 또는 개념 및 작성할 콘텐츠 유형을 이해하는 것이 중요합니다.

이 문서를 읽은 누군가는 무엇을 하거나 이해할 수 있어야 하나요? 콘텐츠에서 논의할 작업 또는 개념을 하나 또는 두 개 선택합니다.
필수적이지 않은 추가 작업, 개념 또는 정보가 있는 경우 문서에서 더 아래에 배치하거나 다른 문서로 이동하거나 완전히 생략할 수 있는지 고려하세요.

의도한 대상 그룹 및 콘텐츠의 핵심 목적에 따라 작성할 콘텐츠 유형을 결정합니다. GitHub Docs은(는) 다음 콘텐츠 형식을 사용합니다.

예를 들어 개념적 콘텐츠 형식을 사용하여 독자가 기능 또는 토픽의 기본 사항과 목표를 달성하는 데 어떻게 도움이 되는지 이해할 수 있습니다. 절차적 콘텐츠 형식을 사용하여 사용자가 처음부터 끝까지 특정 작업을 완료할 수 있도록 지원합니다.

다음 모범 사례를 사용하여 콘텐츠를 구성합니다. 기존 문서에 콘텐츠를 추가할 때 가능하면 기존 구조를 따릅니다.

초기 컨텍스트를 제공합니다. 토픽을 정의하고 판독기와의 관련성을 명시합니다.
중요도 및 관련성을 기준으로 논리적 순서로 콘텐츠를 구성합니다. 우선 순위에 따라 사용자가 필요로 하는 순서대로 정보를 배치합니다.
긴 문장과 단락을 사용하지 마십시오.
- 개념을 하나씩 소개합니다.
- 단락당 하나의 아이디어를 사용합니다.
- 문장당 하나의 아이디어를 사용합니다.
가장 중요한 정보를 강조하세요.
- 각 문장 또는 단락을 가장 중요한 단어와 요점으로 시작합니다.
- 개념을 설명할 때 결론부터 시작한 다음 더 자세히 설명합니다. (이를 "역피라미드형"이라고도 합니다.)
- 복잡한 주제를 설명할 때는 먼저 독자에게 기본 정보를 제공하고 문서의 뒷부분에서 세부 정보를 공개합니다.
의미 있는 부제목을 사용합니다. 관련 단락을 섹션으로 구성합니다. 각 섹션에 고유하고 콘텐츠를 정확하게 설명하는 부제목을 제공합니다.
더 긴 콘텐츠에 대해 페이지 내 링크를 사용하는 것이 좋습니다. 이렇게 하면 독자가 관심 영역으로 이동하고 관련이 없는 콘텐츠를 건너뛸 수 있습니다.

바쁜 사용자가 텍스트를 쉽게 읽고 이해할 수 있도록 합니다.

일반 언어를 사용합니다. 일반적인 일상 단어를 사용하고 가능하면 전문 용어를 사용하지 않습니다. 개발자에게 잘 알려진 용어는 괜찮지만 독자가 GitHub의 작동 방식에 대한 세부 정보를 알고 있다고 가정하지 마십시오.
적극적인 음성을 사용합니다.
간결해야 합니다.
- 단순하고 간단한 문장을 작성합니다.
- 여러 개념이 포함된 복잡한 문장을 사용하지 마십시오.
- 불필요한 세부 정보를 구문 분석합니다.

관련 정보는 스타일 가이드 및 번역할 콘텐츠 작성의 "음성 및 어조"를 참조하세요.

대부분의 읽기 권한자는 문서를 완전히 사용하지 않습니다. 대신 페이지를 스캔 하여 특정 정보를 찾거나 페이지를 훑어보며 개념에 대한 일반적인 아이디어를 얻습니다.

콘텐츠를 스캔하거나 훑어볼 때 읽기 권한자는 큰 텍스트 청크를 건너뜁니다. 제목, 경고, 목록, 테이블, 코드 블록, 시각적 개체 및 각 섹션의 처음 몇 단어와 같이 해당 작업과 관련되거나 페이지에서 눈에 띄는 요소를 찾습니다.

문서에 명확하게 정의된 목적과 구조가 있으면 다음 서식 기술을 적용하여 스캔 및 훑어보기를 위한 콘텐츠를 최적화할 수 있습니다. 이러한 기술은 모든 읽기 권한자가 콘텐츠를 더 쉽게 이해할 수 있도록 하는 데 도움이 될 수 있습니다.

굵게 표시 및 하이퍼링크와 같은 텍스트 강조 표시를 사용하여 가장 중요한 점에 대한 주의를 환기합니다. 텍스트 강조 표시는 너무 많이 사용하지 않습니다. 문서에서 전체 텍스트의 10% 이상을 강조 표시하지 마세요.
서식 요소를 사용하여 콘텐츠를 구분하고 페이지에 공간을 만듭니다. 예시:
- 글머리 기호 목록(선택적 실행 부제목 포함)
- 번호 매기기 목록
- 경고
- 테이블
- 시각적 요소
- 코드 블록 및 코드 주석