Skip to content

Commit 53b82e7

Browse files
lecoursenCopilot
andauthored
Add shared writing principles to always-on content instructions (#62306)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: fcd81257-f535-4567-8ea8-72fb660a530b
1 parent 9dd02bd commit 53b82e7

1 file changed

Lines changed: 14 additions & 0 deletions

File tree

.github/instructions/content-guidelines.instructions.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,20 @@ The strategic priority is simplification: create less content and remove content
1919
* Would a typical internet user figure this out on their own by exploring the UI?
2020
* Is the information presented at the moment the reader actually needs it?
2121

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+
2236
## Intros: pull people in
2337

2438
This section applies mainly to the `intro` frontmatter field and, for conceptual articles, section openings.

0 commit comments

Comments
 (0)