에 대한 다이어그램 만들기 GitHub Docs

GitHub Docs의 다이어그램 정보

다이어그램은 셰이프, 선 및 레이블을 사용하여 개념을 시각적으로 설명합니다. 우리는 GitHub Docs에서 텍스트 정보를 보완하기 위해 다이어그램을 사용합니다.

다이어그램은 정보를 덜 복잡하게 만들지는 않지만 정보를 수신하고 처리하는 다른 방법을 제공합니다. 어떤 사람들은 정보를 읽는 대신 정보를 표시하려고 합니다. 어떤 사람들은 시각적 다이어그램에 참여할 수 없으며 텍스트로 정보를 표시해야 합니다.

다이어그램에는 여러 가지 용도가 있습니다. 다이어그램은 단락 또는 전체 문서를 작성해야 하는 개념에 대한 개략적인 개요를 제공할 수 있습니다. 다른 사용자가 다이어그램을 보고 추가 정보를 더 읽을지 여부를 결정할 수 있습니다. 전체 프로세스를 한 번에 보거나 워크플로의 특정 단계를 마이크로 수준으 이해하여 시스템 수준의 의사 결정에 다이어그램을 사용할 수도 있습니다. 다이어그램은 콘텐츠이며, 모든 콘텐츠와 마찬가지로 사용자의 요구를 신중하게 고려하여 사용자가 가장 잘 사용하는 방법을 결정해야 합니다.

다이어그램은 창의적입니다. 사람들에게 도움이 되는 다이어그램 아이디어가 있다면, 정확히 어떤 도형을 사용하는지와 관계없이 GitHub Docs에 잘 맞을 수 있습니다. 다음 요구 사항 및 권장 사항은 GitHub Docs에 포함될 수 있는 다이어그램을 만드는 데 도움이 됩니다.

다이어그램 체크리스트

다이어그램에 GitHub Docs포함하려면 다음 조건을 충족해야 합니다.

• 다이어그램에는 최대한 많은 사용자가 액세스할 수 있습니다.
  • 다이어그램에는 명확한 시작점이 있으며 따라하기 쉽습니다.
  • 다이어그램은 시각적 형식으로만 전달되는 정보가 없도록 해당 기사에서 전체 텍스트 설명 앞이나 뒤에 위치합니다.
  • 다이어그램은에는 적절한 대비가 있습니다.
  • 다이어그램에는 적절한 대체 텍스트가 있습니다.
  • 다이어그램은 가능한 한 읽을 수 있는 요소로 명확하고 선명합니다.
• 다이어그램에는 수용 기준이 있으며 이 수용 기준을 충족합니다.
  • 다이어그램에는 대상 그룹이 있습니다.
  • 다이어그램에는 적절한 양의 정보와 밀도가 있습니다.
• 다이어그램은 시각적으로 잘 구성되어 있습니다.
  • 다이어그램은 이 콘텐츠 모델에 명시된 스타일을 따릅니다.
  • 다이어그램에는 이해하기 쉽고 탐색할 수 있는 충분한 정보가 있지만 지나치게 장식되거나 불필요하게 복잡하지는 않습니다.

다이어그램 유지 관리

다이어그램 작성자는 다이어그램을 유지 관리할 책임이 있습니다. 다이어그램이 만료된 경우 다이어그램을 GitHub Docs 제거, 업데이트 또는 교체하는 것은 팀의 재량입니다.

다이어그램을 사용하지 않는 경우

다이어그램은 텍스트를 대체하지 않습니다. 그들은 문서에 작성된 정보를 칭찬합니다. 혼동되는 문서를 단순화하거나 수정하기 위해 다이어그램을 추가하지 마세요. 기사 텍스트를 다시 작성하는 것을 고려하시고, 다시 작성된 텍스트를 지원할 수 있는 경우 다이어그램을 추가하십시오.

다이어그램을 사용하는 경우

다이어그램은 GitHub Docs에서, 사용자에게 도움이 되고 단순한 시각적 장식에 그치지 않을 때 사용할 수 있습니다. 다이어그램이 유용한지 확인하려면 다음 사항을 포함하는 수용 기준이 필요합니다.

• 다이어그램의 대상 그룹은 누구인가요?
• 다이어그램의 범위는 어떻게 되나요?
• 다이어그램은 함께 제공되는 텍스트를 어떻게 보완합니까?
• 다이어그램의 효과를 어떻게 평가합니까?

다이어그램은 항상 동일한 정보를 완전히 전달하는 텍스트와 함께 제공해야 합니다.

다이어그램에 대한 수용 기준

다이어그램에 대한 수용 기준을 만들려면 다음 질문에 답변하세요.

다이어그램의 대상 그룹은 누구인가요?

문서와 같은 다이어그램에는 광범위하거나 특정한 대상 그룹이 있을 수 있습니다. 예를 들어, 다이어그램의 대상 독자는 조직을 위해 GitHub Advanced Security, GitHub Code Security 또는 GitHub Secret Protection의 구매를 고려하는 사람들일 수도 있고, GitHub Education의 지원 절차가 어떻게 진행되는지 배우는 학생들일 수도 있습니다.

다이어그램의 범위는 어떻게 되나요?

다이어그램에 정보가 많을수록 만들고 이해하기가 더 어려워집니다. 모든 다이어그램에는 생성을 안내하고 효과를 평가하기 위해 설정된 범위가 필요합니다. 예를 들어, GitHub이(가) 무엇인지 설명하는 다이어그램은 범위가 매우 넓습니다. 모든 GitHub 제품 및 기능에 대한 자세한 정보를 입력하면 혼란스러울 수 있으므로 이 범위의 다이어그램이 광범위한 개요를 제공할 것으로 예상합니다. 반면, GitHub호스팅 실행기와 자체 호스팅 실행기 중 어느 쪽이 사용 사례에 더 적합한지 판단하는 데 도움이 되는 다이어그램은 범위가 더 좁기 때문에 더 구체적이고 세밀한 정보를 다루게 될 가능성이 높습니다.

다이어그램은 함께 제공되는 텍스트를 어떻게 보완합니까?

다이어그램은 가까운 텍스트에 따라 다른 용도로 사용할 수 있습니다. 시스템에 대한 텍스트 설명을 따르는 복잡한 시스템을 보여 주는 다이어그램은 개념 전체를 이해하는 데 도움이 되는 시스템에 대한 시각적 설명을 제공할 수 있습니다. 사용자가 수행하려는 작업을 보여 주는 절차 단계 전의 다이어그램은 일부 사용자가 작업을 성공적으로 완료하도록 준비하는 데 도움이 될 수 있습니다. 다이어그램에는 텍스트를 사용하여 다이어그램을 수행하는 목적이 필요하며, 다이어그램은 문서에서 정보를 전달하는 유일한 방법이 될 수 없습니다.

다이어그램의 효과를 어떻게 평가합니까?

대상 그룹 및 범위를 고려할 때 다이어그램이 효과를 발휘하기 위해 설명해야 하는 정확한 내용을 식별할 수 있어야 합니다. 다이어그램을 GitHub Docs포함하기 전에 다른 사용자가 범위에 적합한 세부 정보 양으로 지정된 대상에게 예상 정보를 설명하는지 검토하고 결정하도록 합니다.

사용할 다이어그램 유형 선택

다양한 사람들이 다양한 다이어그램을 가치있게 생각하며 좋은 다이어그램을 만드는 데 과학만큼이나 많은 예술이 있습니다. 다음 일반 지침은 사용할 다이어그램 유형을 선택하는 데 도움이 될 수 있지만 특정 수용 기준에 더 적합한 고유한 다이어그램이 있을 수도 있습니다.

시간을 설명하는 다이어그램

발생 시기 또는 방법을 설명하는 다이어그램을 만드는 경우 이러한 다이어그램 유형 중 하나를 고려합니다.

• 순서도: 순서도는 프로세스의 단계를 표시하는 데 유용합니다. 이 예제에서 사각형은 프로세스의 단계를 나타내고 다이아몬드는 차트가 두 개의 가능한 엔드포인트로 분기되는 결정 포인트를 나타냅니다.

  

• Gantt 차트: Gantt 차트는 작업이 걸리는 시간과 겹치는 시간을 표시하는 데 유용합니다. 이 예시에서는 가로 축에 "Time"이라는 레이블이 지정되고 파란색 사각형은 세 개의 개별 작업을 나타냅니다. 작업 1과 작업 2가 겹칩니다. 즉, 작업의 일부 이상이 동시에 발생합니다. 작업 3은 다른 작업과 겹치지 않습니다. 즉, 처음 두 작업이 완료된 후에 발생합니다.

  

• 경험 맵: 경험 맵은 시간이 지남에 따라 어떤 항목의 상태를 보여주는 데 유용합니다. 이 예시에서는 가로 축에 "Time"이라는 레이블이 지정되고 세로 축에는 "Something observed or measured"라는 레이블이 지정됩니다. 파란색 점은 특정 시간에 측정값을 표시하고 시간에 따른 추세를 설명하기 위해 선과 연결됩니다.

  

정렬 설정을 설명하는 다이어그램

다이어그램을 만들어 사물이 무엇인지 또는 어디에 있는지 설명하는 경우 이러한 다이어그램 유형 중 하나를 고려합니다.

• 블록 다이어그램: 블록 다이어그램은 항목을 다른 항목 내에 배치하여 항목을 구성하는 방법을 보여 주는 데 유용합니다. 이 예제는 GitHub Docs에서 콘텐츠가 어떻게 구성되는지를 보여 줍니다. 가장 큰 사각형에는 "Category"라고 표시되어 있고, 그 안에는 "Map topics"라고 표시된 사각형이 있으며, 그 안에는 다시 "Articles"라고 표시된 사각형이 있습니다.

  

• 개념 맵: 개념 맵은 사물 간의 관계를 표시하는 데 유용합니다. 레이블이 있거나 없는 다른 줄은 사물이 연결되거나 서로 영향을 미치는 방식을 보여 줍니다. 이 예제에서 네 개의 파란색 사각형은 개념을 나타내고 그 사이의 선은 개념 사이의 서로 다른 관계를 표시합니다.

  

• 계층: 계층은 범주와 하위 범주 사이의 관계를 표시하는 데 유용합니다. 이 예제에서는 계층 구조의 세 가지 수준이 세로로 구성됩니다.

  

컨텍스트를 설명하는 다이어그램

다이어그램을 만들어서 그 이유를 설명하는 경우 이러한 다이어그램 형식 중 하나를 고려합니다.

• Continuum 다이어그램: Continuum 다이어그램은 선형 스펙트럼에 있는 위치를 표시하는 데 유용합니다. 이 예제에서 파란색 사각형은 관심 있는 항목이 Continuum의 옵션 1보다 옵션 2에 더 가깝다는 것을 보여줍니다.

  

• 사분면 다이어그램: 사분면 다이어그램은 두 축 사이의 관계와 두 축에 해당하는 위치를 설명하는 데 유용합니다. 이 예시에서 가로 축은 왼쪽에 "순수 장식용"이라는 레이블이 지정되고 오른쪽에는 "특정 수용 기준을 만족"이라는 레이블이 지정됩니다. 세로 축은 위쪽에는 "Compliment written text"가, 아래쪽에는 "The only way information is presented"라는 레이블이 지정됩니다. "GitHub Docs의 다이어그램"이라고 레이블이 지정된 파란색 사각형은 "작성된 텍스트를 보완"과 "특정 수용 기준을 충족"이 겹쳐 형성되는 우상단 사분면에 있으며, 이는 이 사각형이 그 두 가지 속성을 모두 갖고 있음을 의미합니다.

  

• 벤 다이어그램: 벤 다이어그램은 공유 특성 또는 아이디어의 겹침을 표시하는 데 유용합니다. 원은 개념이나 사물을 나타내며, 원이 겹치는 영역은 사물 간의 공유 특성을 나타냅니다. 이 예시에서는 "Octopus"로 명명된 원과 "Cat"으로 명명된 원이 겹치는 부분은 문어와 고양이의 조합인 "Octocat"으로 명명됩니다.

  

스타일 지침

다음 규칙을 따라 스타일 GitHub Docs에 맞는 다이어그램을 만듭니다.

도형

셰이프는 다이어그램의 개체 또는 개념을 나타냅니다.

UI의 GitHub 요소(예: 8진수, 메뉴 또는 단추)를 사용하여 관련성이 있고 읽기 쉬운 경우 다이어그램을 만들 수 있습니다.

사용자 지정 다이어그램 셰이프의 경우 이러한 셰이프를 관련 의미에 사용합니다.

• 사각형: 사물, 개체, 아이디어.
• 직사각형 스택: 같은 항목의 배수입니다.
• 다이아몬드: 다이어그램 흐름을 따르는 동안 누군가가 내리는 결정입니다.
• 원, 별 또는 기타 셰이프: 사각형이 나타내는 것과 달라야 하는 고유한 항목입니다.

셰이프의 정렬 설정은 의미를 전달할 수 있습니다.

• 한 도형 안에 다른 도형이 있는 경우: 이것은 그 일부를 나타냅니다.
• 화살표가 다른 도형을 가리키는 도형: 이렇게 하면 그것이 이어집니다.
• 도형 아래에 들여쓰기된 도형: 이것은 그 유형 중 하나입니다.
• 다른 셰이프와 선으로 연결된 셰이프: 이것이 저것과 연결되어 있습니다. 선의 두께는 강한 연결을 나타내는 두꺼운 선과 약한 연결을 나타내는 점선으로 의미를 더욱 전달할 수 있습니다.
• 다른 셰이프와 겹치는 셰이프: 이 셰이프는 동일합니다.

라인

선은 다이어그램의 셰이프 간 관계를 나타냅니다.

다양한 유형의 선을 사용하여 관계의 추가적인 의미를 전달합니다.

• 비방향 선: 비방향 선으로 을 연결합니다.
• 화살표로 끝나는 단방향 선: 시퀀스를 표시하거나 개체를 가리킵니다.

• 양쪽에 화살표가 있는 양방향 선: 상호 보호를 나타냅니다.

• 대괄호: 계층 구조를 설정합니다. 일반적으로 웹 페이지에서 쉽게 탐색할 수 있도록 대괄호를 세로로 구성합니다. 계층 구조의 각 수준을 들여쓰기합니다.

레이블

레이블은 시각적 및 언어 표식입니다. 레이블은 25자 이하여야 합니다. 레이블의 대비를 높이려면 텍스트를 사각형에 넣으세요. 다이어그램 만들기가 끝날 때 레이블을 지정하는 것이 더 쉬운 경우가 많습니다.

키

키는 그래프의 다른 요소가 무엇인지 설명하거나 관계를 명시적으로 명확히 하여 이해를 돕습니다. 모든 다이어그램에 키가 필요한 것은 아닙니다.

키는 다이어그램에 없는 새 정보를 도입할 수 없습니다. 키는 지나치게 복잡한 다이어그램을 수정할 수 없습니다. 키는 잘못된 레이블이 지정된 개체 또는 관계를 정의해서는 안 됩니다.

키는 셰이프, 색 또는 기타 시각적 요소를 설명하는 데 사용해야 합니다. 키에는 크기 조정 및 조작에 대한 인용 또는 설명도 포함될 수 있습니다. 키에는 순서도에서 시작할 위치와 같은 몇 가지 명령이 포함될 수 있지만 대부분의 명령은 다이어그램을 소개하는 텍스트에 있어야 합니다.

색상들

다이어그램에 색이 필요한 경우 Primer 디자인 시스템에 정의된 색을사용합니다. 더 많은 사용자가 다이어그램에 액세스할 수 있도록 하기 위해 색상만이 정보를 전달하는 유일한 방법이 될 수는 없습니다. 예를 들어 색을 사용하여 관계를 나타내는 경우 선이나 다른 시각적 요소를 사용하여 동일한 정보를 전달해야 합니다.

다이어그램 GitHub Docs 의 기본 설정 색은 다음과 같습니다.

색	16진수 코드
검정	#24292f
파랑
#0969DA
회색	#57606a
녹색
#1a7f37
자주색	#8250df
빨간색
#cf222e

기술 사양

• PNG 파일 형식
• 정적 이미지만 해당(GIF 불가)
• 파일 크기 250KB 이하
• merge-conflict-diagram.png 대신 diagram-02.png처럼 설명적인 파일 이름

작은 해상도로 보기 어려운 다이어그램을 만들어야 하는 경우 관련 리포지토리 또는 기타 적절한 위치에 더 큰 버전의 다이어그램에 대한 링크를 포함합니다. 예는 Actions Runner 컨트롤러을(를) 참조하세요.

다이어그램을 만드는 도구

다이어그램을 사용하는 데 권장되는 도구는 Primer 색 및 기타 자산에 액세스할 수 있도록 하는 Figma입니다. 그러나 원하는 경우 다른 프로그램을 사용할 수 있습니다. 위의 스타일 가이드에서 셰이프 규칙을 따르고 Primer 디자인 시스템에 정의된 색을 사용합니다.

접근성

다이어그램에는 적절한 대비 및 대체 텍스트가 있어야 합니다.

Primer 디자인 시스템에 정의된 색을 사용하는 경우 다이어그램에 적절한 대비가 있어야 합니다. 다른 배경색에서 대비를 검사하려면 색 대비 분석기를 사용하세요.

다이어그램의 모양과 다이어그램이 문서에 포함된 이유를 설명하는 다이어그램의 대체 텍스트를 작성합니다. 너무 길어 유용할 수 있으므로 다이어그램이 대체 텍스트에 전달하는 모든 것을 설명하지 마세요. 대체 텍스트 작성에 대한 자세한 내용은 스타일 가이드을(를) 참조하세요.

다이어그램의 모든 정보는 다이어그램과 함께 텍스트로도 전달해야 합니다.

버전 관리

일부 다이어그램은 모든 GitHub 계획(GitHub Free, ,GitHub ProGitHub Team, GitHub Enterprise Cloud및GitHub Enterprise Server)에 적용됩니다. 이 경우 버전 관리는 필요하지 않습니다.

다이어그램이 일부 계획 또는 버전과만 관련된 경우 다이어그램은 GitHub Enterprise ServerLiquid 조건문으로 버전이 지정되어야 합니다. 콘텐츠가 처음 생성될 때 이 버전 관리를 추가해야 할 수도 있고, 기능 업데이트 또는 GitHub Enterprise Server 릴리스를 위해 콘텐츠가 업데이트될 때 추가해야 할 수도 있습니다.

다이어그램이 오직 일부 버전과 관련이 있으며 빠르게 구식이 되기 쉬운 경우, 유지 관리 옵션이 필요한 정보를 전달하는 데 더 좋을 수 있는지 고려해야 합니다.

소스 컨트롤

다이어그램은 assets/images/help/ 리포지토리의 docs 디렉터리에 있는 관련 디렉터리에 저장됩니다. 새 다이어그램을 만드는 경우 적절한 폴더에 추가합니다. 기존 다이어그램을 업데이트하는 경우 기존 다이어그램을 업데이트된 버전으로 바꿉니다.

새 다이어그램을 만들 때 Docs Figma 팀의 다이어그램 프로젝트에 추가하거나 Figma 파일의 복사본을 Docs 팀의 구성원에게 제공합니다. 다른 프로그램에서 다이어그램을 만드는 경우 이 가이드의 GitHub Docs 요구 사항 및 권장 사항을 충족하는 경우 다이어그램을 포함할 수 있지만, 최신 상태가 되면 업데이트하지 않고 제거될 가능성이 훨씬 높습니다.

예제

은 효과적으로 다른 사각형 내의 사각형을 사용하여 클라우드에 포함된 코드스페이스의 부분을 시각적으로 설명하고 화살표를 사용하여 클라우드에서 호스트되는 코드스페이스와 로컬 편집기 간의 관계를 표시합니다.