Skip to content

Add AI disclosure guidelines to documentation #4247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add AI disclosure guidelines to documentation #4247

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,24 @@
# .NET Aspire Documentation Guidelines

## Disclosure

For any Markdown files generated by AI, please disclose that they were created with the assistance of AI. Add the following frontmatter key/value pair:

```markdown
ai-usage: ai-generated
```

## 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
Expand All @@ -16,6 +27,7 @@ Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-g
- 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
Expand All @@ -25,13 +37,15 @@ Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-g
- 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:
Expand All @@ -44,14 +58,17 @@ If unsure, use API browser: `https://learn.microsoft.com/api/apibrowser/dotnet/s
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`

- Breaking changes: Include directions from [`.github/prompts/breaking-change.md`](./prompts/breaking-change.md).
Loading