You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+5-10Lines changed: 5 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,11 @@
1
1
When writing documentation, follow these guidelines:
2
2
3
-
# Documentation Writing Instructions
4
-
5
-
These are our documentation writing style guidelines.
6
-
7
-
## General Style tips
3
+
## General style tips
8
4
9
5
* Get to the point fast. Be concise and clear.
10
6
* Talk like a person.
11
7
* Simpler is better.
12
-
* Be brief. Give customers just enough information to make decisions confidently. Prune every excess word.
8
+
* Be brief. Give customers just enough information to make decisions confidently. Prune excess words.
13
9
* Break up long sentences.
14
10
* Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/). If there's a conflict between the following guidelines and the Microsoft Writing Style Guide, ask how to resolve it.
15
11
@@ -20,7 +16,7 @@ These are our documentation writing style guidelines.
20
16
* Use active voice where the subject performs the action.
21
17
* Write in second person (you) to speak directly to readers.
22
18
* Use gender-neutral language.
23
-
* Avoid multiple -ing words that can create ambiguity.
19
+
* Avoid multiple -ing words that could create ambiguity.
24
20
* Keep prepositional phrases simple and clear.
25
21
* Place modifiers close to what they modify.
26
22
* Use a conversational tone with contractions.
@@ -35,7 +31,6 @@ These are our documentation writing style guidelines.
35
31
* Always capitalize proper nouns.
36
32
* Don’t capitalize the spelled-out form of an acronym unless it's a proper noun.
37
33
* Use title-style capitalization for product and service names.
38
-
* In programming languages, follow the traditional capitalization of keywords and other special terms.
39
34
* Don't use all uppercase for emphasis.
40
35
41
36
## Numbers
@@ -84,13 +79,13 @@ These are our documentation writing style guidelines.
84
79
*`[!CAUTION]` Negative potential consequences of an action.
85
80
*`[!WARNING]` Dangerous certain consequences of an action.
86
81
87
-
## Links
82
+
## Adding links
88
83
89
84
* Add links to related topics and resources where appropriate.
90
85
* Links to other documentation articles should be relative, not absolute. Start relative links with `/docs/` and include the `.md` suffix. 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.
91
86
* Links to bookmarks within the same article should be relative and start with `#`.
92
87
* Link descriptions should be descriptive and make sense on their own. Don't use "click here" or "this link" or "here".
93
-
* When you are going to refer to another file or an article on the web, use this format: "For more information, see [C++ language reference](../cpp/cpp-language-reference.md)." The exception to this is the See Also links at the end of an article. Those should be markdown links and contain the title of the article you link to as the descriptive portion of the link.
88
+
* When you are going to refer to another file or an article on the web, use this format: "For more information, see [descriptive name of link](link path)." The exception to this is the See Also links at the end of an article. Those should be markdown links and contain the title of the article you link to as the descriptive portion of the link.
0 commit comments