You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/instructions/content-guidelines.instructions.md
+14Lines changed: 14 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -19,6 +19,20 @@ The strategic priority is simplification: create less content and remove content
19
19
* Would a typical internet user figure this out on their own by exploring the UI?
20
20
* Is the information presented at the moment the reader actually needs it?
21
21
22
+
## Give opinionated, actionable guidance
23
+
24
+
This applies whenever you give the reader advice or present ways to accomplish a task.
25
+
26
+
* Be opinionated when there is a better way: when several approaches exist, recommend the best one and explain why, rather than presenting all options as equally valid. When they are genuinely equivalent, stay neutral.
27
+
* Tell users the best practice AND how to follow it: whenever you state a best practice, pair it with concrete steps or an example so the reader can act on it, never the advice alone.
28
+
29
+
## Focus on the reader's purpose, not the product
30
+
31
+
Frame an article around what the reader is trying to accomplish, not the product or feature they use to do it. This applies when naming an article or deciding what a new or substantially reworked article should cover; do not use it to justify restructuring an article during a small edit.
32
+
33
+
* Title articles by the reader's goal, not the product or feature. For example, "Secure your enterprise", not "Use GitHub Advanced Security".
34
+
* Scope articles around a task, not a product. When a task naturally spans multiple features or products, look for the opportunity to cover them together in one task-focused article or tutorial rather than splitting into per-product articles. Keep each article to a single purpose (the task): combine features only when they serve that same task, not to bundle unrelated capabilities.
35
+
22
36
## Intros: pull people in
23
37
24
38
This section applies mainly to the `intro` frontmatter field and, for conceptual articles, section openings.
Copy file name to clipboardExpand all lines: .github/instructions/content.instructions.md
+19Lines changed: 19 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,6 +16,14 @@ Before committing content changes, always:
16
16
3.**Verify [AUTOTITLE] links** point to existing articles
17
17
4.**Run tests** on changed content: `npm run test -- src/content-render/tests/render-changed-and-deleted-files.ts`
18
18
19
+
## Accuracy and flagging uncertainty
20
+
21
+
AI assistants can produce plausible but incorrect information. To protect readers and writers:
22
+
23
+
* Never fabricate product behavior, settings, permissions, API parameters, or limits. If you cannot verify a detail from the source material or the product itself, say so instead of guessing.
24
+
* Flag uncertainty at the level of the specific claim, not the whole article. Identify the individual sentence, step, value, or setting you are unsure about, rather than labeling an entire article as "needs review."
25
+
* After writing or editing, give the writer a checklist of each specific claim to verify, noting where it appears (the exact step or sentence) and why it needs checking. Prioritize claims where being wrong could have serious consequences, such as security, authentication, permissions, billing, or any irreversible action, and recommend confirming those with the relevant product or engineering team.
26
+
19
27
## Bullet lists
20
28
21
29
The bulleted points in a bullet list should always be denoted in Markdown using an asterisk, not a hyphen.
@@ -107,6 +115,17 @@ For such content, DO NOT use in-article Liquid versioning such as `{% ifversion
107
115
108
116
All articles that are ONLY for GitHub Enterprise Server (GHES) should be versioned in the frontmatter using feature-based versioning defined in `data/features/`.
109
117
118
+
### Versioning for GHES content: always use feature-based versioning
119
+
120
+
If content is intended to ship to GitHub Enterprise Server, use **feature-based versioning (FBV)**.
121
+
122
+
* Do **not** suggest removing GHES frontmatter versioning or hardcode version strings (for example, `free-pro-team@latest`) just to make links or tests pass.
123
+
* If CI fails because a GHES link cannot be built, treat that as a versioning mismatch—not a signal to de-scope GHES.
124
+
* Add or reuse the appropriate feature flag in `data/features/`. Use it in `versions.feature` frontmatter when an article's availability follows the feature, and use Liquid conditionals only for version-specific blocks within a broader article.
125
+
* Keep frontmatter and in-article versioning aligned so links render for every supported version.
126
+
127
+
For guidance, see [About feature-based versioning](https://docs.github.com/en/contributing/writing-for-github-docs/versioning-documentation#about-feature-based-versioning).
128
+
110
129
### FPT, GHEC, GHES articles
111
130
112
131
All articles that are versioned for all of FPT, GHEC, and GHES in the frontmatter MAY require certain blocks of content to be versioned using in-article Liquid versioning. Before recommending this, check if this is really the case.
# Editing Copilot content instruction and agent files
6
+
7
+
This applies when you add, edit, or remove a Copilot instruction or shared agent file that guides how **content** (articles, data files) is written. It does **not** apply to code instructions or agents owned by the engineering team (for example `code.instructions.md`).
8
+
9
+
When it applies, you **must** first read the instruction-architecture doc in full and follow it:
Read the current version every time (from a local `github/docs-team` checkout if you have one, otherwise fetch the URL); do not rely on your memory of it, because it changes. If you cannot access it, say so and stop rather than guessing.
0 commit comments