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
When writing documentation, follow the following guidelines:
1
+
When writing documentation, follow these guidelines:
2
2
3
-
- Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
3
+
- Follow the style of the [Microsoft Writing Style Guide](https://learn.microsoft.com/style-guide/welcome/).
4
4
- Headings should be in sentence case, not title case. Don't use gerunds in titles.
5
5
- Use the active voice whenever possible, and second person to address the reader directly.
6
6
- Use a conversational tone with contractions.
@@ -14,14 +14,14 @@ When writing documentation, follow the following guidelines:
14
14
- Number ordered list items all as "1." instead of "1.", "2.", etc. Use bullets for unordered lists.
15
15
- 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.
16
16
- Put raw URLs within angle brackets.
17
-
- When you are going to refer to another file or an article on the web, use a link. For example, "For more information, see [C++ language reference](../cpp/cpp-language-reference.md)."
17
+
- 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.
18
18
- 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.
19
19
- 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.
20
-
- If you're adding a new Markdown file, the following indicates where it should go the folder structure. If you aren't sure, ask. The following folder structure is how it looks on my hard drive. To map to GitHub, for example, C:\Users\twhitney\repos\cpp-docs-pr\docs\linux is docs/linux
21
-
If the file is about Linux, put it in the C:\Users\twhitney\repos\cpp-docs-pr\docs\linux folder.
22
-
If the file is about the C++ Standard Template Library (STL), put it in the C:\Users\twhitney\repos\cpp-docs-pr\docs\standard-library folder.
23
-
If the file is about the C runtime, put it in the C:\Users\twhitney\repos\cpp-docs-pr\docs\c-runtime-library folder.
24
-
If the file is about the C++ language, put it in the C:\Users\twhitney\repos\cpp-docs-pr\docs\cpp folder.
25
-
If the file is about a C++ feature specific to the Visual Studio IDE, put it in the C:\Users\twhitney\repos\cpp-docs-pr\docs\ide folder.
26
-
If the file is about the build process or modules, put it in the C:\Users\twhitney\repos\cpp-docs-pr\docs\build\reference folder.
27
-
If the file is about Build Insights, put it in the C:\Users\twhitney\repos\cpp-docs-pr\docs\build-insights folder.
20
+
- If you're adding a new Markdown file, the following indicates where it should go the folder structure. If you aren't sure, ask.
21
+
If the new file is about Linux, put it in the docs/linux folder.
22
+
If the new file is about the C++ Standard Template Library (STL), put it in the docs/standard-library folder.
23
+
If the new file is about the C runtime, put it in the docs/c-runtime-library folder.
24
+
If the new file is about the C++ language, put it in the docs/cpp folder.
25
+
If the new file is about a C++ feature specific to the Visual Studio IDE, put it in the docs/ide folder.
26
+
If the new file is about the build process or modules, put it in the docs/build\reference folder.
27
+
If the new file is about Build Insights, put it in the docs/build-insights folder.
0 commit comments