Skip to content

Commit 23c7175

Browse files
emilyistoofunkyemilyistoofunky
authored
Migrate content model and templates to the public repo (#19141)
* Add content model * Add templates * Update contributing README and CONTRIBUTING * Update content for partners * Update based on feedback
1 parent 31b84e5 commit 23c7175

File tree

7 files changed

+773
-58
lines changed

7 files changed

+773
-58
lines changed

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,8 @@ Here's some information that might be helpful while working on a Docs PR:
135135

136136
- [Content style guide for GitHub Docs](/contributing/content-style-guide.md) - This guide covers GitHub-specific information about how we style our content and images. It also links to the resources we use for general style guidelines.
137137

138+
- [Content model](/contributing/content-model.md) and [content templates](/contributing/content-templates.md) - The content model describes the purpose of each type of content we use in GitHub Docs and how to write for each type. The templates allow you to quickly get started with new articles.
139+
138140
- [Reusables](/data/reusables/README.md) - We use reusables to help us keep content up to date. Instead of writing the same long string of information in several articles, we create a reusable, then call it from the individual articles.
139141

140142
- [Variables](/data/variables/README.md) - We use variables the same way we use reusables. Variables are for short strings of reusable text.

‎contributing/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@ Check out our [contributing.md](../CONTRIBUTING.md) to see all the ways you can
55
Here, you'll find additional information that might be helpful as you work on a pull request in this repo.
66

77
- [development](./development.md) - steps for getting this app running on your local machine
8-
- [content markup reference](./content-markup-reference.md) - how to use markup and features specific to the GitHub Docs site
8+
- [content markup reference](./content-markup-reference.md) - how to use markup and features specific to the GitHub Docs site
99
- [content style guide](./content-style-guide.md) - style guidance specific to GitHub Docs content and additional resources for writing clear, helpful content
10+
- [content model](./content-model.md) - the content types that make up GitHub Docs and how to write them
11+
- [content templates](./content-templates.md) - handy templates to get you started with a new article
1012
- [deployments](./deployments.md) - how our staging and production environments work
1113
- [liquid helpers](./liquid-helpers.md) - using liquid helpers for versioning in our docs
1214
- [localization checklist](./localization-checklist.md) - making sure your content is ready to be translated

‎contributing/content-model.md‎

Lines changed: 452 additions & 0 deletions
Large diffs are not rendered by default.

‎contributing/content-templates.md‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
# Templates for GitHub Docs content
2+
3+
You can copy any of these templates into a new Markdown file as the first step in creating a new article and opening a pull request.
4+
5+
- [Conceptual](#conceptual)
6+
- [Referential](#referential)
7+
- [Procedural](#procedural)
8+
- [Quickstart](#quickstart)
9+
- [Tutorial](#tutorial)
10+
- [Language guide for GitHub Actions](#language-guide-for-github-actions)
11+
12+
## Conceptual
13+
14+
Use the [content model](/contributing/content-model.md#conceptual) for full instructions and examples on how to write conceptual content.
15+
16+
```
17+
---
18+
title: About [subject]
19+
intro: 'Article intro. See tips for a great intro below.'
20+
product: '{{ optional product callout }}'
21+
productVersions:
22+
---
23+
24+
<!-- Follow the guidelines in https://github.com/github/docs/blob/main/contributing/content-model.md#conceptual to write this article.-- >
25+
<!-- Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://github.com/github/docs/blob/main/contributing/content-model.md#intro. -->
26+
<!-- For product callout info, see https://github.com/github/docs/tree/main/content#product.-->
27+
<!-- For product version instructions, see https://github.com/github/docs/tree/main/content#productversions.-->
28+
<!-- Remove these comments from your article file when you're done writing. -->
29+
30+
### A section here
31+
32+
<!-- Write one or two paragraphs about the main idea of your topic, as a summary. -->
33+
<!-- Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our TOC. -->
34+
35+
### Another section here
36+
37+
<!-- Write one or two paragraphs about another element of your topic. -->
38+
<!-- Keep adding headers and sections until you've completed your article. -->
39+
40+
### Further reading
41+
42+
<!-- Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. -->
43+
44+
- "[Article title](article-URL)"
45+
```
46+
47+
## Referential
48+
49+
Use the [content model](https://github.com/github/docs/blob/main/contributing/content-model.md#referential) for full instructions and examples on how to write referential content.
50+
51+
```
52+
---
53+
title: Nouns describing your subject
54+
intro: 'Article intro. See tips for a great intro below.'
55+
product: '{{ optional product callout }}'
56+
productVersions:
57+
---
58+
59+
<!-- Follow the guidelines in https://github.com/github/docs/blob/main/contributing/content-model.md#referential to write this article.-- >
60+
<!-- Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://github.com/github/docs/blob/main/contributing/content-model.md#intro. -->
61+
<!-- For product callout info, see https://github.com/github/docs/tree/main/content#product.-->
62+
<!-- For product version instructions, see https://github.com/github/docs/tree/main/content#productversions.-->
63+
<!-- Remove these comments from your article file when you're done writing -->
64+
65+
### A section here
66+
67+
<!-- Write one or two paragraphs about the main idea of your topic, as a summary. -->
68+
<!-- Make sure you don't have any content that isn't preceded by a header, or it won't be linkable in our TOC. -->
69+
70+
### Another section here
71+
72+
<!-- Write one or two paragraphs about another element of your topic. -->
73+
<!-- Keep adding headers and sections until you've completed your article. -->
74+
75+
### Further reading
76+
77+
<!-- Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. -->
78+
79+
- "[Article title](article-URL)"
80+
```
81+
82+
## Procedural
83+
84+
Use the [content model](https://github.com/github/docs/blob/main/contributing/content-model.md#procedural) for full instructions and examples on how to write procedural content.
85+
86+
```
87+
---
88+
title: Start with a gerund
89+
intro: 'Article intro. See tips for a great intro below.'
90+
product: '{{ optional product callout }}'
91+
productVersions:
92+
---
93+
94+
<!-- Follow the guidelines in https://github.com/github/docs/blob/main/contributing/content-model.md#procedural to write this article.-- >
95+
<!-- Great intros give readers a quick understanding of what's in the article, so they can tell whether it's relevant to them before moving ahead. For more tips, see https://github.com/github/docs/blob/main/contributing/content-model.md#intro. -->
96+
<!-- For product callout info, see https://github.com/github/docs/tree/main/content#product.-->
97+
<!-- For product version instructions, see https://github.com/github/docs/tree/main/content#productversions.-->
98+
<!-- Remove these comments from your article file when you're done writing -->
99+
100+
### Procedural section header here
101+
102+
<!-- Include prerequisite information or specific permissions information here. -->
103+
<!-- Then write procedural steps following the instructions in https://github.com/github/docs/blob/main/contributing/content-model.md#procedural-steps. -->
104+
<!-- Check if there's already a reusable string for the step you want to write in https://github.com/github/docs/tree/main/data/reusables. Tip: Look at the source file for a procedure located in the same area of the user interface to find reusables. -->
105+
106+
### Optionally, another procedural section here
107+
108+
<!-- Keep adding procedures until you've finished writing your article. -->
109+
110+
### Further reading
111+
112+
<!-- Optionally, include a bulleted list of related articles the user can reference to extend the concepts covered in this article. Consider linking to procedural articles or tutorials that help the user use the information in your article. -->
113+
114+
- "[Article title](article-URL)"
115+
```
116+
117+
## Quickstart
118+
119+
Use the [content model](https://github.com/github/docs/blob/main/contributing/content-model.md#quickstart) for full instructions and examples on how to write quickstarts.
120+
121+
```
122+
---
123+
title: Quickstart title
124+
intro: 'Article intro. Highlight that the guide is quick and to the point.'
125+
productVersions:
126+
---
127+
128+
<!-- Follow the guidelines in https://github.com/github/docs/blob/main/contributing/content-model.md#quickstart to write this article.-->
129+
<!-- For product version instructions, see https://github.com/github/docs/tree/main/content#productversions.-->
130+
<!-- The entire quickstart should be about 600 words long or take about five minutes to read.-->
131+
<!-- Remove these comments from your article file when you're done writing -->
132+
133+
### Introduction
134+
135+
<!-- Build on the quick phrasing above by:
136+
- Clarifying the audience
137+
- Clearly stating prerequisites and prior knowledge needed
138+
- Stating what the user will accomplish or build-->
139+
140+
### Step one: Action the user will take
141+
142+
<!-- In one sentence, describe what the user will do in this step -->
143+
<!-- Steps should break down the tasks the user will complete in sequential order -->
144+
<!-- Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. -->
145+
146+
#### Task chunk
147+
148+
<!-- A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. -->
149+
<!-- An example might be creating a PAT for the action to use and then storing it in secrets -->
150+
<!-- For UI based tasks, include the button or options the users should click -->
151+
<!-- If the task adds code, include the code in context (don't just show `needs: setup` show the entire `setup` and `dependent` jobs) -->
152+
153+
#### Another task chunk
154+
155+
<!-- remove all of these comments when you're done -->
156+
157+
### Step 2: Do the next thing
158+
159+
<!-- Rinse and repeat, adding steps and tasks until the tutorial is complete -->
160+
161+
### Next steps
162+
163+
<!-- Provide a quick recap of what has been accomplished in the quick start as a means of transitioning to next steps. Include 2-3 actionable next steps that the user take after completing the quickstart. Always link to conceptual content on the feature or product. You can also link off to other related information on docs.github.com or in GitHub Learning Labs. -->
164+
```
165+
166+
## Tutorial
167+
168+
Use the [content model](https://github.com/github/docs/blob/main/contributing/content-model.md#tutorial) for full instructions and examples on how to write tutorials.
169+
170+
```
171+
---
172+
title: Tutorial title
173+
intro: 'Article intro. See tips for a great intro below'
174+
product: '{{ optional product callout }}'
175+
productVersions:
176+
---
177+
178+
<!-- Follow the instructions in https://github.com/github/docs/blob/main/contributing/content-model.md#quickstart to write this article.-->
179+
<!-- Great intros clarify who the tutorial is intended for, state what the user will accomplish, and state the technologies that will be used.-->
180+
<!-- For product callout info, see https://github.com/github/docs/tree/main/content#product.-->
181+
<!-- For product version instructions, see https://github.com/github/docs/tree/main/content#productversions.-->
182+
<!-- Remove these comments from your article file when you're done writing -->
183+
184+
### Introduction
185+
186+
<!-- The tutorial introduction should include the following in a short paragraph:
187+
188+
- Clarify audience
189+
- State prerequisites and prior knowledge needed
190+
- State what the user will accomplish or build and the user problem it solves
191+
- Link to an example of the project the user will complete -->
192+
193+
### Step 1: Action the user will take
194+
195+
<!-- In one sentence, describe what the user will do in this step -->
196+
<!-- Steps should break down the tasks the user will complete in sequential order -->
197+
<!-- Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. -->
198+
199+
#### Task chunk
200+
201+
<!-- A step may require the user to perform several tasks - break those tasks down into chunks, allowing the user to scan quickly to find their place if they navigated away from this screen to perform the task. -->
202+
<!-- An example might be creating a PAT for the action to use and then storing it in secrets -->
203+
<!-- For UI based tasks, include the button or options the users should click -->
204+
<!-- If the task adds code, include the code in context (don't just show `needs: setup` show the entire `setup` and `dependent` jobs) -->
205+
206+
#### Another task chunk
207+
208+
<!-- remove all of these comments when you're done -->
209+
210+
### Step 2: Do the next thing
211+
212+
<!-- Rinse and repeat, adding steps and tasks until the tutorial is complete
213+
214+
<!-- remember to show code snippets in context -->
215+
216+
<!-- ```yaml
217+
on:
218+
schedule:
219+
- cron: "40 19 * * *"
220+
``` -->
221+
222+
### Further reading
223+
224+
<!-- include a bulleted list of tutorials or articles the user can reference to extend the concepts taught in this tutorial -->
225+
226+
- "[Article title](article-URL)"
227+
```
228+
229+
## Language guides for GitHub Actions
230+
231+
Use the [tutorial content model](hhttps://github.com/github/docs/blob/main/contributing/content-model.md#tutorial) for full instructions and examples on how to language and framework guides for GitHub Actions.
232+
233+
```
234+
---
235+
title: Guide title
236+
intro: 'Article intro. See tips for a great intro below'
237+
product: '{{ site.data.reusables.gated-features.actions }}'
238+
productVersions:
239+
---
240+
241+
<!--
242+
- Great intros clarify who the guide is intended for, state what the user will accomplish, and state the technologies that will be used.
243+
- Intros are typically 1-3 sentence summaries, with a longer "Introduction" section that follows.
244+
- Remove these comments from your article file when you're done writing
245+
-->
246+
247+
### Introduction
248+
249+
<!--
250+
The language guide introduction should include the following in a short paragraph:
251+
- Clarify audience.
252+
- State prerequisites and prior knowledge needed.
253+
- Should the user have read any other articles?
254+
- State what the user will accomplish or build and the user problem it solves.
255+
-->
256+
257+
### Starting with the <language> workflow template
258+
259+
<!--
260+
Language guides typically walk through and build upon a starter workflow template. If that format doesn't work, you can include a boilerplate workflow.
261+
- Link to the GitHub Actions CI starter workflow as the boilerplate reference code and then walk through and build on that code in this guide: https://github.com/actions/starter-workflows/tree/master/ci
262+
- Provide instructions for adding the starter workflow template to a repository.
263+
- Include the starter template workflow code.
264+
-->
265+
266+
### Running on different operating systems
267+
268+
<!--
269+
Include a brief overview of how to choose the runner environment. These should be alternatives to what operating system is presented in the starter workflow/boilerplate template.
270+
-->
271+
272+
### Configuring the <language> version
273+
<!--
274+
- Describe when and how to use available setup actions that configure the version of the language on the runner (ex. actions/setup-node).
275+
- How does the setup action configure the version and what happens when the version isn't supported in the environment. What is the default version, when no version is configured.
276+
- Include any additional features the setup action might provide that are useful to CI.
277+
- If applicable, provide examples of configuring exact versions or major/minor versions.
278+
- Include information about software already installed on GitHub-hosted runners or software configuration necessary to build and test the project.
279+
- Provide examples of configuring build matrix strategies.
280+
- Link out to any docs about available software on the GitHub-hosted runners. (Ex. https://docs.github.com/en/actions/reference/software-installed-on-github-hosted-runners).
281+
- Include code samples.
282+
-->
283+
284+
### Installing dependencies
285+
286+
<!--
287+
- Include example of installing dependencies to prepare for building and testing.
288+
- Are there any dependencies or scenarios where people might need to install packages globally?
289+
- Include examples of common package managers.
290+
- If the language is supported by GitHub Packages, include an example installing dependencies from GitHub.
291+
- Include code samples.
292+
-->
293+
294+
### Caching dependencies
295+
296+
<!--
297+
Include an example of restoring cached dependencies. We'll want to link out to the article about caching for more information (https://docs.github.com/en/actions/configuring-and-managing-workflows/caching-dependencies-to-speed-up-workflows).
298+
-->
299+
300+
### Building your code
301+
302+
<!--
303+
- Include any compile steps.
304+
- Include any test commands.
305+
- Note that you can use the same commands that your repository needs to build and test your code by simply replacing the commands in the `run` keyword.
306+
- Include any basic examples or commands specific to test frameworks.
307+
- Include any common databases or services that might be needed. If so, we can link out to the services guides in the docs (https://docs.github.com/en/actions/configuring-and-managing-workflows/using-databases-and-service-containers).
308+
-->
309+
310+
### Packaging workflow data as artifacts
311+
312+
<!--
313+
This section can simply link out to https://docs.github.com/en/actions/configuring-and-managing-workflows/persisting-workflow-data-using-artifacts or provide additional information about which artifacts might be typical to upload for a CI workflow.
314+
-->
315+
```

‎contributing/github-partners/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,4 +16,4 @@ You should consider creating a tutorial when:
1616
- The user may have implemented a similar solution in the past using a different product.
1717
- The user wants to validate whether the solution is appropriate for their needs.
1818

19-
Get started with this template [here](tutorial.md).
19+
Get started with the tutorial template [here](/contributing/content-templates.md#tutorial).

0 commit comments

Comments
 (0)