Creating diagrams for GitHub Docs - GitHub Docs
Skip to main content Skip to content Collapse sidebar Expand sidebar Creating diagrams for GitHub Docs This guide explains when and how to create diagrams for GitHub Docs. In this article About diagrams in GitHub Docs Diagrams use shapes, lines, and labels to explain concepts visually. We use diagrams to support textual information in GitHub Docs. Diagrams do not make information less complex, but they present a different way to receive and process information.
Some people want to be shown information instead of reading it. Some people cannot engage with visual diagrams and need the information to be presented in text. There are many uses for diagrams. Diagrams can provide high-level overviews of concepts that require paragraphs or entire articles to write about. Someone could view the diagram and then decide if they want to read more for additional information. Diagrams can also be used for system-level decision making by seeing an entire process at once or micro-level understanding of specific steps in a workflow.
Diagrams are content, and like all content merit careful consideration of user needs to determine how to best use them. Diagrams are creative. If you have an idea for a diagram that helps people, no matter the exact shapes that it uses, it might be a good fit for GitHub Docs. The following requirements and recommendations will help you create a diagram that can be included in GitHub Docs. Diagram checklist To be included in GitHub Docs, a diagram must meet the following criteria.
The diagram can be accessed by as many users as possible. Diagrams have clear starting points and are easy to follow. Diagrams are preceded or followed by complete text descriptions in the article in which they appear, with no information conveyed entirely in visual form. Diagrams have appropriate contrast. Diagrams have appropriate alternate text. Diagrams are clear and crisp with elements as legible as possible. The diagram has acceptance criteria and meets them.
Diagrams have an audience. Diagrams have the right amount of information and density. The diagram is visually sound. Diagrams follow the style set forth in this content model. Diagrams have enough information to be easy to understand and navigate, but they are not overly decorated or needlessly complex. Maintaining diagrams The creator of a diagram is responsible for maintaining it. If a diagram is out of date, it is the GitHub Docs team's discretion to remove, update, or replace the diagram.
When not to use diagrams Diagrams are not a substitute for text. They compliment written information in articles. Do not add a diagram to try to simplify or fix an article that is confusing. Consider rewriting the article text and possibly adding a diagram if it supports the rewritten text. When to use diagrams Diagrams can be used in GitHub Docs when they help people and are not just visual adornment. To determine if a diagram is helpful, it needs acceptance criteria that include the following: Who is the audience for the diagram?
What is the scope of the diagram? How does the diagram complements the accompanying text? How will you evaluate the diagram's effectiveness? A diagram must always be accompanied by text that fully conveys the same information. Acceptance criteria for diagrams To create acceptance criteria for a diagram, answer these questions. Who is the audience for the diagram? Diagrams, like articles, can have broad or specific audiences.
For example, diagram audiences could be people who are considering purchasing GitHub Advanced Security, GitHub Code Security, or GitHub Secret Protection for their organization or students learning how the application process for GitHub Education works. What is the scope of the diagram? The more information in a diagram, the more difficult it becomes to create and understand. All diagrams need an established scope to guide their creation and evaluate their effectiveness.
For example, a diagram that explains what GitHub is has a very large scope. It would likely be confusing if it went into detailed information about every GitHub product and feature, so we would expect a diagram of this scope to provide a broad overview. In contrast, a diagram that helps someone evaluate whether GitHub-hosted runners or self-hosted runners are more appropriate for their uses will likely go into more specific and nuanced information since it has a more narrow scope.
How does the diagram complement the accompanying text? A diagram can serve a different purpose depending on what text it is near. A diagram depicting a complex system following a text description of the system can offer a visual explanation of the system that will help some people understand the concept as a whole. A diagram before procedural steps that illustrates the task someone is about to do can help some people prepare to complete the task successfully.
A diagram needs a purpose that it accomplishes with the text, and a diagram can never be the only way information is communicated in an article. How will you evaluate the diagram's effectiveness? Considering the audience and scope, you should be able to identify what exactly a diagram needs to explain for it to be effective. Before including a diagram in GitHub Docs, have someone else review and determine if it explains the expected information to the specified audience with the amount of detail appropriate to the scope.
Choosing what type of diagram to use Different people will find different diagrams valuable and there is as much art as science to creating a good diagram. The following general guidelines can help you choose what type of diagram to use, but you may also have a unique diagram that is a better fit for your specific acceptance criteria. Diagrams that explain time If you are creating a diagram to explain when or how something happens, consider one of these diagram types.
Flowchart : Flowcharts are useful for showing the steps in a process. In this example, the rectangles represent steps in a process and the diamond represents a decision point where the chart branches into two possible endpoints. Gantt chart : Gantt charts are useful for showing how long tasks take and when they overlap. In this example, the horizontal axis is labeled "Time" and the blue rectangles represent three discrete tasks.
Task 1 and task 2 overlap, which means that at least part of the tasks happen at the same time. Task 3 does not overlap with the other tasks, which means that it happens after the first two are completed. Journey map : Journey maps are useful for showing how the state of something over time. In this example, the horizontal axis is labeled "Time" and the vertical axis is labeled "Something observed or measured." Blue dots mark measurements at specific times and they are connected with a line to illustrate the trend over time.
Diagrams that explain arrangement If you are creating a diagram to explain what or where things are, consider one of these diagram types. Block diagram : Block diagrams are useful for showing how things are organized by putting items within other items. This example shows how content is organized in GitHub Docs with the largest rectangle labeled "Category," a rectangle within that labeled "Map topics," and a rectangle within that labeled "Articles." Concept map : Concept maps are useful for showing relationships between things.
Different lines with or without labels show how things are connected or affect each other. In this example, the four blue rectangles represent concepts and the lines between them show different relationships between them. Hierarchy : Hierarchies are useful for showing relationships between categories and subcategories. In this example, three levels of a hierarchy are organized vertically. Diagrams that explain context If you are creating a diagram to explain why something is the way that it is, consider one of these diagram types.
Continuum diagram : Continuum diagrams are useful for showing where things fall on a li
The rest of this page is on the live site.