GitHub 설명서 정보
GitHub에서 정확하고, 가치 있고, 포괄적이며, 접근 가능하고, 사용하기 쉬운 설명서를 만들기 위해 노력하고 있습니다.
GitHub Docs에 기여하기 전에 잠시 시간을 내어 GitHub의 설명서 철학 및 콘텐츠 디자인 원칙을 숙지하세요.
GitHub 설명서를 작성하는 모범 사례
새 문서를 만들거나 기존 문서를 업데이트하는 경우 GitHub Docs에 대해 작성할 때 다음 지침을 따라야 합니다.
사용자 요구에 맞게 콘텐츠 정렬
시작하기 전에 작성 대상, 해당 목표, 문서에서 다룰 핵심 작업 또는 개념 및 작성할 콘텐츠 유형을 이해하는 것이 중요합니다.
대상 그룹 정의
- 이 콘텐츠를 읽는 대상은 누구인가요?
- 수행하려는 작업이 무엇인가요?
핵심 목적 정의
- 이 문서를 읽은 누군가는 무엇을 하거나 이해할 수 있어야 하나요? 콘텐츠에서 논의할 작업 또는 개념을 하나 또는 두 개 선택합니다.
- 필수적이지 않은 추가 작업, 개념 또는 정보가 있는 경우 문서에서 더 아래에 배치하거나 다른 문서로 이동하거나 완전히 생략할 수 있는지 고려하세요.
콘텐츠 유형 결정
의도한 대상 그룹 및 콘텐츠의 핵심 목적에 따라 작성할 콘텐츠 유형을 결정합니다. GitHub Docs은(는) 다음 콘텐츠 형식을 사용합니다.
예를 들어 개념적 콘텐츠 형식을 사용하여 독자가 기능 또는 토픽의 기본 사항과 목표를 달성하는 데 어떻게 도움이 되는지 이해할 수 있습니다. 절차적 콘텐츠 형식을 사용하여 사용자가 처음부터 끝까지 특정 작업을 완료할 수 있도록 지원합니다.
가독성을 위한 콘텐츠 구조화
다음 모범 사례를 사용하여 콘텐츠를 구성합니다. 기존 문서에 콘텐츠를 추가할 때 가능하면 기존 구조를 따릅니다.
- 초기 컨텍스트를 제공합니다. 토픽을 정의하고 판독기와의 관련성을 명시합니다.
- 중요도 및 관련성을 기준으로 논리적 순서로 콘텐츠를 구성합니다. 우선 순위에 따라 사용자가 필요로 하는 순서대로 정보를 배치합니다.
- 긴 문장과 단락을 사용하지 마십시오.
- 개념을 하나씩 소개합니다.
- 단락당 하나의 아이디어를 사용합니다.
- 문장당 하나의 아이디어를 사용합니다.
- 가장 중요한 정보를 강조하세요.
- 각 문장 또는 단락을 가장 중요한 단어와 요점으로 시작합니다.
- 개념을 설명할 때 결론부터 시작한 다음 더 자세히 설명합니다. (이를 "역피라미드형"이라고도 합니다.)
- 복잡한 주제를 설명할 때는 먼저 독자에게 기본 정보를 제공하고 문서의 뒷부분에서 세부 정보를 공개합니다.
- 의미 있는 부제목을 사용합니다. 관련 단락을 섹션으로 구성합니다. 각 섹션에 고유하고 콘텐츠를 정확하게 설명하는 부제목을 제공합니다.
- 더 긴 콘텐츠에 대해 페이지 내 링크를 사용하는 것이 좋습니다. 이렇게 하면 독자가 관심 영역으로 이동하고 관련이 없는 콘텐츠를 건너뛸 수 있습니다.
가독성을 위해 쓰기
바쁜 사용자가 텍스트를 쉽게 읽고 이해할 수 있도록 합니다.
- 일반 언어를 사용합니다. 일반적인 일상 단어를 사용하고 가능하면 전문 용어를 사용하지 않습니다. 개발자에게 잘 알려진 용어는 괜찮지만 독자가 GitHub의 작동 방식에 대한 세부 정보를 알고 있다고 가정하지 마십시오.
- 적극적인 음성을 사용합니다.
- 간결해야 합니다.
- 단순하고 간단한 문장을 작성합니다.
- 여러 개념이 포함된 복잡한 문장을 사용하지 마십시오.
- 불필요한 세부 정보를 구문 분석합니다.
관련 정보는 스타일 가이드 및 번역할 콘텐츠 작성의 "음성 및 어조"를 참조하세요.
스캔 가능성을 위한 형식
대부분의 읽기 권한자는 문서를 완전히 사용하지 않습니다. 대신 페이지를 스캔 하여 특정 정보를 찾거나 페이지를 훑어보며 개념에 대한 일반적인 아이디어를 얻습니다.
콘텐츠를 스캔하거나 훑어볼 때 읽기 권한자는 큰 텍스트 청크를 건너뜁니다. 제목, 설명, 목록, 테이블, 코드 블록, 시각적 개체 및 각 섹션의 처음 몇 단어와 같이 해당 작업과 관련되거나 페이지에서 눈에 띄는 요소를 찾습니다.
문서에 명확하게 정의된 목적과 구조가 있으면 다음 서식 기술을 적용하여 스캔 및 훑어보기를 위한 콘텐츠를 최적화할 수 있습니다. 이러한 기술은 모든 읽기 권한자가 콘텐츠를 더 쉽게 이해할 수 있도록 하는 데 도움이 될 수 있습니다.
- 굵게 표시 및 하이퍼링크와 같은 텍스트 강조 표시를 사용하여 가장 중요한 점에 대한 주의를 환기합니다. 텍스트 강조 표시는 너무 많이 사용하지 않습니다. 문서에서 전체 텍스트의 10% 이상을 강조 표시하지 마세요.
- 서식 요소를 사용하여 콘텐츠를 구분하고 페이지에 공간을 만듭니다. 예시:
- 글머리 기호 목록(선택적 실행 부제목 포함)
- 번호 매기기 목록
- 설명
- 테이블
- 화면 표시
- 코드 블록 및 코드 주석
추가 참고 자료
- "스타일 가이드"
- "콘텐츠 모델 정보"
- "GitHub Docs 문서의 내용"
- "가독성 지침", 콘텐츠 디자인 런던
- "간결함을 위해 디지털 콘텐츠 다시 작성", Nielsen Norman Group