|
1 | | -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. |
| 1 | +# .NET Documentation Guidelines |
2 | 2 |
|
3 | | -When writing documentation, follow the following guidelines: |
| 3 | +## Disclosure |
4 | 4 |
|
5 | | -Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework). |
| 5 | +For any Markdown files generated by AI, always disclose that they were created with the assistance of AI. Add the following frontmatter key/value pair: |
6 | 6 |
|
7 | | -Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/). |
| 7 | +```markdown |
| 8 | +ai-usage: ai-generated |
| 9 | +``` |
8 | 10 |
|
9 | | -Headings should be in sentence case, not title case. Don't use gerunds in titles. |
| 11 | +## Terminology |
10 | 12 |
|
11 | | -Use the active voice whenever possible, and second person to address the reader directly. |
| 13 | +- Unless otherwise specified, all .NET content refers to modern .NET (not .NET Framework). |
12 | 14 |
|
13 | | -Use a conversational tone with contractions. |
| 15 | +## Writing Style |
14 | 16 |
|
15 | | -Be concise. |
| 17 | +Follow [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) with these specifics: |
16 | 18 |
|
17 | | -Break up long sentences. |
| 19 | +### Voice and Tone |
18 | 20 |
|
19 | | -Use the present tense for instructions and descriptions. For example, "The method returns a value" instead of "The method will return a value." |
| 21 | +- Active voice, second person addressing reader directly. |
| 22 | +- Conversational tone with contractions. |
| 23 | +- Present tense for instructions/descriptions. |
| 24 | +- Imperative mood for instructions ("Call the method" not "You should call the method"). |
| 25 | +- Use "might" instead of "may" for possibility. |
| 26 | +- Use "can" instead of "may" for permissible actions. |
| 27 | +- Avoid "we"/"our" referring to documentation authors or product teams. |
20 | 28 |
|
21 | | -Do not use "we" or "our" to refer to the authors of the documentation. |
| 29 | +### Structure and Format |
22 | 30 |
|
23 | | -Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method." |
| 31 | +- Sentence case headings (no gerunds in titles). |
| 32 | +- Be concise, break up long sentences. |
| 33 | +- Oxford comma in lists. |
| 34 | +- Number all ordered list items as "1." (not sequential numbering like "1.", "2.", "3.", etc.) |
| 35 | +- Use bullets for unordered lists. |
| 36 | +- Ordered and unordered lists should use complete sentences with proper punctuation, ending with a period if it's more than three words. |
| 37 | +- Avoid "etc." or "and so on" - provide complete lists or use "for example". |
| 38 | +- No consecutive headings without content between them. |
24 | 39 |
|
25 | | -Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception." |
| 40 | +### Formatting Conventions |
26 | 41 |
|
27 | | -Use the Oxford comma in lists of three or more items. |
| 42 | +- **Bold** for UI elements. |
| 43 | +- `Code style` for file names, folders, custom types, non-localizable text. |
| 44 | +- Raw URLs in angle brackets. |
| 45 | +- Use relative links for files in this repo. |
| 46 | +- Remove `https://learn.microsoft.com/en-us` from learn.microsoft.com links. |
28 | 47 |
|
29 | | -Number ordered list items all as "1." instead of "1.", "2.", etc. |
| 48 | +## API References |
30 | 49 |
|
31 | | -Use bullets for unordered lists. Unless *all* the bullet list items are three words or less, each bullet item should end with a period. |
| 50 | +Use cross-references: `<xref:api-doc-ID>`. |
32 | 51 |
|
33 | | -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. |
| 52 | +To find API doc IDs: |
| 53 | +1. Check XML files in https://github.com/dotnet/dotnet-api-docs. |
| 54 | +2. For types: `Value` attribute of `<TypeSignature>` where `Language="DocId"` (omit first 2 characters). |
| 55 | +3. For members: `Value` attribute of `<MemberSignature>` where `Language="DocId"` (omit first 2 characters). |
34 | 56 |
|
35 | | -Put raw URLs within angle brackets. |
| 57 | +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` and then use the `url` value from the results as a manual link. |
36 | 58 |
|
37 | | -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. |
| 59 | +## Code Snippets |
38 | 60 |
|
39 | | -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>. |
| 61 | +For snippets >6 lines: |
| 62 | +1. Create `./snippets/my-doc/language` folder in same directory as document (for a document named `my-doc.md`) where language is either vb (for visual basic) or csharp (for c#). Omit the `language` component when the document is in the `docs/visual-basic`, `docs/csharp`, or `docs/fsharp` folders. |
| 63 | +1. Add snippet as separate code file. |
| 64 | +1. Include simple project file targeting latest .NET. |
| 65 | +1. All code should use the latest stable versions/features. |
| 66 | +1. Create examples in both C# and Visual Basic unless the article referencing the snippet resides in the in the `csharp`, `fsharp`, and `visual-basic` language folders. |
| 67 | +1. When you add code, use code comments sparingly because they don't get localized. You can use them to briefly clarify code-specific details (such as logic, parameters, or edge cases). Put any critical information and context in the markdown text of the referencing article. |
40 | 68 |
|
41 | | -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. |
| 69 | +## File Naming |
42 | 70 |
|
43 | | -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. |
| 71 | +New Markdown files: lowercase with hyphens, omit filler words (the, a, etc.). |
44 | 72 |
|
45 | | -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. |
| 73 | +## Special Cases |
| 74 | + |
| 75 | +- Breaking changes: Include directions from `.github/prompts/breaking-change.md`. |
| 76 | +- When you (Copilot) are assigned an issue in GitHub, 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. |
0 commit comments