Add documentation review guidelines to .github/instructions and align README writing style section

.github/instructions/docs.instructions.md

@@ -0,0 +1,59 @@
+---
+applyTo: "astro/src/content/**/*.{md,mdx}"
+---
+
+# Documentation Review Guidelines
+
+## Purpose
+
+Review documentation for Duende Software products (IdentityServer, BFF, etc.). Focus on writing quality, accuracy, and consistency with the project's authoring standards.
+
+## Writing Style
+
+- Tone: friendly, educational, patient — "a senior engineer sitting next to you helping with your homework."
+- Use active voice. "Enable" not "Enabled" or "Enabling".
+- Use second person: "you" is the reader, "we" is Duende Software.
+- Sentence case in body text. Title Case for titles.
+- Use the Oxford comma.
+- Avoid filler words: "very", "simple", "easy", "just".
+- Prefer plain words: "use" not "utilize", "set up" not "facilitate", "help" not "assist", "about" not "regarding".
+- Keep it concise. Don't pad. Longer isn't better.
+- Explain *why* something works, not just *what* to change.
+- Expand acronyms on first use: "Multi-Factor Authentication (MFA)".
+- If it sounds like a robot wrote it, flag it.
+
+## Frontmatter
+
+- Must have `title`, `description`, and `date` (YYYY-MM-DD format).
+- May have `sidebar` with `label` and `order`. For long `title`, the `label` is used as a shorter entry in the navigation bar, and should be shorter than `title`.
+
+## Linking Rules
+
+- Prefer internal links over external links.
+- Internal links must start at the content root (e.g. `/identityserver/troubleshooting/index.md`) and include the `.md` or `.mdx` extension.
+- External links must use HTTPS.
+- Link relevant text: prefer `learn more about [improving sign-in]` over `click [here]`.
+- Long links (75+ chars) or repeated links should use markdown anchor syntax at the bottom of the file.
+- When linking externally, include a sentence about what the reader will find.
+
+## Markdown Style
+
+- Use `*` for unordered lists, not `-`.
+- Use inline links `[text](url)` unless the link is repeated or very long.
+- Internal links must include the file extension (`.md` or `.mdx`).
+
+## Code Blocks
+
+- Use triple backticks with a language identifier (`csharp`, `bash`, `json`, `html`, `javascript`, `typescript`, `css`).
+- Prefer `csharp` over `cs` for C#.
+- Add a title as a comment in the first line (e.g. `// Program.cs`).
+- Code should not require horizontal scrolling — keep it concise.
+- C# examples should use latest syntax (top-level statements, collection expressions).
+- Examples should be runnable and complete — "copy-paste from docs" is the goal.
+- Use backticks for inline references to properties, classes, symbols, and values (including HTTP status codes like `404`).
+- Code blocks must start at column 0 with no excessive leading whitespace.
+- Mention NuGet packages with `dotnet add package ...` in a `bash` block and link to the NuGet Gallery.
+
+## Redirects
+
+- When a page is moved, check that `redirect_from` frontmatter is present with the old path.

README.md

@@ -111,14 +111,18 @@ WebStorm has Grazie as a built-in spell checker and grammar checker, and support
 
 ### Writing Style
 
+* General style: "big brother sitting next to you helping with your homework." Friendly, educational, patient. You're a senior engineer who has seen this before and wants to help the reader understand, not just find a quick fix.
 * Use the active voice. For example, use "Enable" instead of "Enabled" or "Enabling".
 * Use the second person ("you" not "I" or "we"). "You" is the reader of the documentation. "We" is Duende Software.
 * Use sentence case in text. Titles use Title Case.
 * Use the Oxford comma.
 * Avoid words like "very", "simple", "easy", ...
 * "As well as" can be written as "and".
-* Avoid flowery language.
+* Use plain words: "use" not "utilize", "set up" not "facilitate", "help" not "assist", "about" not "regarding", ... (unless technically precise).
+* Avoid flowery language. Keep it concise. Answer thoroughly, but don't pad. Longer isn't better.
+* Educational, not pedantic: Explain *why* something works, not just *what* to change. Don't over-explain things that are likely already known. When in doubt, include some basic info and reference relevant other sources with more background.
 * When using acronyms, use the full form with parentheses the first time you use it. For example, use "Multi-Factor Authentication (MFA)" instead of "MFA".
+* Read it out loud. If it sounds like a robot wrote it, rewrite it.
 
 ### Linking Rules