Revise documentation guidelines for clarity and structure (#4194)

Author: IEvangelist

.github/copilot-instructions.md

@@ -1,43 +1,57 @@
-When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, check to make sure there are no build warnings under the OpenPublishing.Build status check. If there are, open the build report (under View Details) and resolve any build warnings you introduced.
-
-When writing documentation or editing .md files, follow the following guidelines:
-
-Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework).
-
-Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
-
-Headings should be in sentence case, not title case. Don't use gerunds in titles.
-
-Use the active voice whenever possible, and second person to address the reader directly.
-
-Use a conversational tone with contractions.
-
-Be concise.
-
-Break up long sentences.
-
-Use the present tense for instructions and descriptions. For example, "The method returns a value" instead of "The method will return a value."
-
-Do not use "we" or "our" to refer to the authors of the documentation.
-
-Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method."
-
-Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception."
-
-Use the Oxford comma in lists of three or more items.
-
-Number ordered list items all as "1." instead of "1.", "2.", etc. Use bullets for unordered lists.
-
-Use **bold** when referring to UI elements. Use `code style` for file names and folders, custom types, and other text that should never be localized.
-
-Put raw URLs within angle brackets.
-
-Include links to related topics and resources where appropriate. Use relative links if the target file lives in this repo. If you add a link to another page on learn.microsoft.com that's not in this repo, remove https://learn.microsoft.com/en-us from the link.
-
-When mentioning APIs, use cross-references to the API documentation. These links are formatted as <xref:api-doc-ID>. You can find the API doc ID in the XML files in the https://github.com/dotnet/dotnet-api-docs repository. For types, the doc ID is the value of the `Value` attribute of the `<TypeSignature>` element where the `Language` attribute value is `DocId`. For other (member) APIs, the doc ID is the value of the `Value` attribute of the `<MemberSignature>` element where the `Language` attribute value is `DocId`. Omit the first two characters of the DocId. For example, the xref link for System.String is <xref:System.String>.
-
-If you're assigned a GitHub issue that's labeled "breaking-change", include the prompt directions in the .github/prompts/breaking-change.md file in this repo.
-
-If you include a code snippet that's more than 6 lines long, put it in a separate .cs file in a folder named "snippets" in the same folder as the document. Within the "snippets" folder, add a new directory with the name of the document. For example, if the document is named "my-doc.md", create a folder named "snippets/my-doc" folder. Also add a simple .csproj file to the same directory that targets the latest version of .NET. It can be a library or executable project.
-
-If you're adding a new Markdown file, it should be named in all lowercase with hyphens separating words. Also, omit any filler words such as "the" or "a" from the file name.
+# .NET Aspire Documentation Guidelines
+
+## Terminology
+- First mention: ".NET Aspire", subsequent mentions: "Aspire"
+- All .NET content refers to modern .NET (not .NET Framework)
+
+## Writing Style
+Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) with these specifics:
+
+### Voice and Tone
+- Active voice, second person addressing reader directly
+- Conversational tone with contractions
+- Present tense for instructions/descriptions
+- Imperative mood for instructions ("Call the method" not "You should call the method")
+- Use "might" instead of "may" for possibility
+- Avoid "we"/"our" referring to documentation authors
+
+### Structure and Format
+- Sentence case headings (no gerunds in titles)
+- Be concise, break up long sentences
+- Oxford comma in lists
+- Number all ordered list items as "1." (not sequential numbering like "1.", "2.", "3.", etc.)
+- Complete sentences with proper punctuation in all list items
+- Avoid "etc." or "and so on" - provide complete lists or use "for example"
+- No consecutive headings without content between them
+
+### Formatting Conventions
+- **Bold** for UI elements
+- `Code style` for file names, folders, custom types, non-localizable text
+- Raw URLs in angle brackets
+- Use relative links for files in this repo
+- Remove `https://learn.microsoft.com/en-us` from learn.microsoft.com links
+
+## API References
+Use cross-references: `<xref:api-doc-ID>`
+
+To find API doc IDs:
+1. Check XML files in https://github.com/dotnet/dotnet-api-docs
+2. For types: `Value` attribute of `<TypeSignature>` where `Language="DocId"` (omit first 2 characters)
+3. For members: `Value` attribute of `<MemberSignature>` where `Language="DocId"` (omit first 2 characters)
+
+If unsure, use API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/search?api-version=0.2&locale=en-us&search={API_NAME}&$skip=0&$top=5`
+
+Use the `url` value from results for manual links.
+
+## Code Snippets
+For snippets >6 lines:
+1. Create `snippets/my-doc/` folder in same directory as document (for a document named `my-doc.md`)
+1. Add snippet as separate `.cs` file
+1. Include simple `.csproj` targeting latest .NET
+1. All code should use the latest stable versions/features
+
+## File Naming
+New Markdown files: lowercase with hyphens, omit filler words (the, a, etc.)
+
+## Special Cases
+- Breaking changes: Include directions from `.github/prompts/breaking-change.md`