Skip to content

Commit 7c642a4

Browse files
Steve Wintonemilyistoofunkyrunleonarun
authored
Add issue template to guide partner documentation contributions (github#17998)
* Add issue template for partner-owned documentation * Add partner name and URL requirement * Fix typo * Place emphasis on automation not possession * Soften compliance requirement * Clarify that applications must be accepted * Fix typo * Clarify that the tasks are the partner's responsibility to complete * Use lower case representation of Pull Request Co-authored-by: Emily Gould <4822039+emilyistoofunky@users.noreply.github.com> * Tweak intent of issue template Co-authored-by: Emily Gould <4822039+emilyistoofunky@users.noreply.github.com> * Merge supporting material under PR section * Add bandwidth expectations * Add templates for partner guides * Fix typo: s/production/product * Add link to general contributing guidelines * Include teams to be mentioned for awareness * Add further documentation requirements * Update contributing/github-partners/README.md Co-authored-by: Emily Gould <4822039+emilyistoofunky@users.noreply.github.com> * Add tutorial template for partners * Provide only one template -- the Tutorial template * Document use of contributor YAML frontmatter * Remove internal repo references * Resolve tests/meta failures Co-authored-by: Emily Gould <4822039+emilyistoofunky@users.noreply.github.com> Co-authored-by: Leona B. Campbell <3880403+runleonarun@users.noreply.github.com>
1 parent be6f869 commit 7c642a4

3 files changed

Lines changed: 120 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/partner-contributed-documentation.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
name: Partner-owned product documentation
3+
about: Initiate a set of tasks to be completed by a GitHub partner wishing to document how their product works with GitHub
4+
title: ''
5+
labels:
6+
- partner
7+
assignees: ''
8+
---
9+
10+
<!--
11+
Thank you for your interest in contributing to the GitHub documentation.
12+
13+
This issue template is only for use by GitHub's Technology Partners who wish to contribute documentation explaining how the partner's product works with GitHub, making it straightforward for our shared customers to adopt the product into their workflow.
14+
15+
As a general guide, we estimate we have bandwidth for prioritizing and reviewing up to 3 partner contributions per quarter.
16+
17+
Please be sure to complete all items in the checklists that follow, and feel free to comment with any questions. A member of the team will be glad to support you.
18+
-->
19+
20+
## Pre-requisites
21+
22+
- [ ] Prior to submitting documentation, please apply to join the GitHub Technology Partner Program: [partner.github.com/apply](https://partner.github.com/apply?partnershipType=Technology+Partner). Please feel free to proceed once your application is approved.
23+
24+
## Tasks
25+
26+
Please be sure to complete each of the following:
27+
28+
**Third-party product documentation:**
29+
30+
- [ ] MUST follow our [general contributing guidelines](CONTRIBUTING.md) for voice and markup format.
31+
- [ ] MUST emphasize how the third-party product works with GitHub.
32+
- [ ] MUST be written in Markdown format, using [one of the templates provided](contributing/github-partners/README.md#templates)
33+
- [ ] MUST include the name and URL of the GitHub technology partner responsible for maintenance of the documentation being contributed. This should be added via the `contributor.name` and `contributor.URL` properties in the template's YAML frontmatter.
34+
- [ ] MUST be proposed via a pull request to this repo following [the GitHub Flow](https://guides.github.com/introduction/flow/).
35+
- [ ] MUST be located in the root of [the `content` folder](content). Your filename MUST match the GitHub technology partner name, and use the `.md` file extension.
36+
37+
**The `Pull Request`:**
38+
39+
- [ ] MUST reference this issue, e.g. via `closes #<this issue number>`
40+
- [ ] MUST pass the automated CI checks
41+
- [ ] MUST include links to supporting material demonstrating the functionality being documented (this can be a link to a public GitHub repo, _or_ a video / screencast walkthrough)
42+
43+
Once all tasks are completed, please mention `@github/docs-content` for next steps.
44+
45+
/cc @github/partner-engineering for :eyes:

‎contributing/github-partners/README.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# GitHub Partners
2+
3+
This folder contains templates to be used by GitHub's technology partners when contributing documentation, such as guides.
4+
5+
To get started, please [open an issue using this link](https://github.com/github/docs/issues/new?template=partner-contributed-documentation.md).
6+
7+
## Templates
8+
9+
### Tutorial template
10+
Tutorials guide the reader through an entire workflow to complete a task.
11+
12+
You should consider creating a tutorial when:
13+
14+
- The user has a basic understanding of the product and is interested in extending their use and understanding to solve a specific problem.
15+
- The user is looking for expert advice and a detailed discussion on best practices related their problem.
16+
- The user may have implemented a similar solution in the past using a different product.
17+
- The user wants to validate whether the solution is appropriate for their needs.
18+
19+
Get started with this template [here](tutorial.md).

‎contributing/github-partners/tutorial.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
title: Tutorial title
3+
intro: 'Article intro. See tips for a great intro below'
4+
product: '{{ optional product callout }}'
5+
productVersions:
6+
contributor:
7+
name:
8+
URL:
9+
---
10+
11+
<!-- Remember to add the tutorial title, intro, product version, contributor name, and contributor URL above -->
12+
<!-- Great intros clarify who the tutorial is intended for, state what the user will accomplish, state the technology(ies) that will be used.-->
13+
14+
### Introduction
15+
16+
<!-- The tutorial introduction should include the following in a short paragraph:
17+
18+
- Clarify audience
19+
- State prerequisites and prior knowledge needed
20+
- State what the user will accomplish or build and the user problem it solves
21+
- Link to an example of the project the user will complete -->
22+
23+
### Step 1: Action the user will take
24+
25+
<!-- In one sentence, describe what the user will do in this step -->
26+
<!-- Steps should break down the tasks the user will complete in sequential order -->
27+
<!-- Avoid replicating conceptual information that is covered elsewhere, provide inline links instead. Only include conceptual information unique to this use case. -->
28+
29+
#### Task chunk
30+
31+
<!-- 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. -->
32+
<!-- An example might be creating a PAT for the action to use and then storing it in secrets -->
33+
<!-- For UI based tasks, include the button or options the users should click -->
34+
<!-- If the task adds code, include the code in context (don't just show `needs: setup` show the entire `setup` and `dependent` jobs) -->
35+
36+
#### Another task chunk
37+
38+
<!-- remove all of these comments when you're done -->
39+
40+
### Step 2: Do the next thing
41+
42+
<!-- Rinse and repeat, adding steps and tasks until the tutorial is complete
43+
44+
<!-- remember to show code snippets in context -->
45+
46+
```yaml
47+
on:
48+
schedule:
49+
- cron: "40 19 * * *"
50+
```
51+
52+
### Further reading
53+
54+
<!-- include a bulleted list of tutorials or articles the user can reference to extend the concepts taught in this tutorial -->
55+
56+
- "[Article title](article-URL)"

0 commit comments

Comments
 (0)