Main to live (#1053)

* Update PULL_REQUEST_TEMPLATE.md * Update section on xref links * Fix link * Update Contribute/content/how-to-write-links.md Co-authored-by: David Pine <[email protected]> * Remove list of OpenSource repos * add skills navigator FAQ with breadcrumb & TOC * fix second title: * fix paths and restore breadcrumb file * another attempt at breadcrumb * remove redirect * move docset * Initialize Docs repository: https://github.com/MicrosoftDocs/Contribute of branch main * Initialize Docs repository: https://github.com/MicrosoftDocs/Contribute of branch main * resolve conflicts * remove duplicate tag * fix build errors. * remove unnecessary toc * fix branch change * fix 88 * remove docset again * Update docfx.json * Update .openpublishing.publish.config.json --------- Co-authored-by: Mike Kinsman <[email protected]> Co-authored-by: Genevieve Warren <[email protected]> Co-authored-by: David Pine <[email protected]> Co-authored-by: Sean Wheeler <[email protected]> Co-authored-by: Brian MacKinney <[email protected]>
MicrosoftDocs · Oct 4, 2024 · ed27f21 · ed27f21
1 parent 1a5a05b
commit ed27f21
Show file tree

Hide file tree

Showing 8 changed files with 91 additions and 103 deletions.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -15,4 +15,4 @@ Thanks for contributing to the [Microsoft Learn contributor guide](https://learn
 
 ## Need help?
 
-If you have an open PR, tag the PR reviewers in a comment with your question: `@carlyrevier, @jehchow`
+If you have an open PR, tag the PR reviewers in a comment with your question: `@mikekinsman, @jehchow`
diff --git a/.openpublishing.publish.config.json b/.openpublishing.publish.config.json
@@ -1,17 +1,5 @@
 {
   "docsets_to_publish": [
-    {
-      "docset_name": "ai-navigator",
-      "build_source_folder": "ai-navigator",
-      "build_output_subfolder": "ai-navigator",
-      "locale": "en-us",
-      "monikers": [],
-      "open_to_public_contributors": true,
-      "type_mapping": {
-        "Conceptual": "Content"
-      },
-      "build_entry_point": "docs"
-    },
     {
       "docset_name": "ContributionGuide",
       "build_source_folder": "Contribute",
@@ -32,6 +20,21 @@
       },
       "build_entry_point": "docs",
       "template_folder": "_themes"
+    },
+    {
+      "docset_name": "ai-navigator",
+      "build_source_folder": "ai-navigator",
+      "build_output_subfolder": "ai-navigator",
+      "locale": "en-us",
+      "monikers": [],
+      "moniker_ranges": [],
+      "open_to_public_contributors": false,
+      "type_mapping": {
+        "Conceptual": "Content"
+      },
+      "build_entry_point": "docs",
+      "template_folder": "_themes"
+
     }
   ],
   "notification_subscribers": [],
@@ -78,4 +81,4 @@
   "skip_source_output_uploading": false,
   "contribution_branch_mappings": {},
   "need_generate_pdf_url_template": true
-}
+}
diff --git a/Contribute/content/how-to-write-links.md b/Contribute/content/how-to-write-links.md
@@ -6,16 +6,16 @@ ms.service: learn
 ms.custom: external-contributor-guide
 author: gewarren
 ms.author: gewarren
-ms.date: 03/31/2020
+ms.date: 09/23/2024
 ---
 # Use links in documentation
 
 This article describes how to use hyperlinks from pages hosted at Microsoft Learn. Links are easy to add into markdown with a few varying conventions. Links point users to content in the same page, in other neighboring pages, or on external sites and URLs.
 
-The Microsoft Learn backend uses Open Publishing Services (OPS), which supports [CommonMark][]-compliant markdown parsed through the [Markdig][] parsing engine. This markdown flavor is mostly compatible with [GitHub Flavored Markdown (GFM)][GFM], as most docs are stored in GitHub and can be edited there. Additional functionality is added through Markdown extensions.
+The Microsoft Learn backend uses Open Publishing Services (OPS), which supports [CommonMark][]-compliant Markdown parsed through the [Markdig][] parsing engine. This Markdown flavor is mostly compatible with [GitHub Flavored Markdown (GFM)][GFM], as most docs are stored in GitHub and can be edited there. Additional functionality is added through Markdown extensions.
 
 > [!IMPORTANT]
-> All links must be secure (`https` vs `http`) whenever the target supports it (which the vast majority should).
+> All links must be secure (`https` vs `http`) whenever the target supports it.
 
 ## Link text
 
@@ -155,10 +155,10 @@ To go to a section on another page.
 
 ## XRef (cross reference) links
 
-XRef links are the recommended way to link to APIs, because they're validated at build time. To link to auto-generated API reference pages in the current docset or other docsets, use XRef links with the unique ID ([UID](#determine-the-uid)) of the type or member.
+XRef links are the recommended way to link to APIs, because they make it easy to customize the link text. Additionally, they're validated at build time, and if the URL to the API reference were to change, the link would still work. To link to auto-generated API reference pages in the current docset or other docsets, use XRef links with the unique ID ([UID](#determine-the-uid)) of the type or member.
 
 > [!TIP]
-> You can use the [Learn Markdown extension for VS Code][docsextension] (part of the Learn Authoring Pack) to insert .NET XRref links that are surfaced in the [.NET API Browser][].
+> The [API Reference Link Helper extension for VS Code](https://github.com/IEvangelist/xref-helper) makes it super easy to insert .NET API Xref links into Markdown and XML files.
 
 Check if the API you want to link to is published on [Microsoft Learn](/) by typing all or some of its full name in the [.NET API browser][] or [Windows UWP][] search box. If you don't see any results displayed, the type isn't yet on Microsoft Learn.
 
@@ -190,80 +190,40 @@ Examples:
 
 - **\[String class](xref:System.String)** displays as [String class](xref:System.String).
 
-The `displayProperty=fullName` query parameter works the same way as `displayProperty=nameWithType` for classes. That is, the link text becomes **namespace.classname**. However, for members, the link text displays as **namespace.classname.membername**, which may be undesirable.
+The `displayProperty=fullName` query parameter works the same way as `displayProperty=nameWithType` for classes. That is, the link text becomes **namespace.classname**. However, for members, the link text displays as **namespace.classname.membername**, which might be undesirable.
 
 > [!NOTE]
-> UIDs are case sensitive. For example, `<xref:System.Object>` resolves correctly but `<xref:system.object>` does not.
-
-### XRef build warnings and incremental builds
-
-An incremental build only builds files that have changed or been affected by a change. If you see a build warning about an invalid XREF link, but the link is actually valid, this could be because the build was incremental. The file causing the warning didn't change, so it wasn't built and past warnings were replayed. The warning will disappear when the file changes or if you trigger a full build (you can start a full build on ops.microsoft.com). This is a drawback to incremental builds, because DocFX can't detect a data update inside the XREF service.
+> UIDs are case sensitive. For example, `<xref:System.Object>` resolves correctly, but `<xref:system.object>` does not.
 
 ### Determine the UID
 
-The UID is usually the fully qualified class or member name. There are at least two ways to determine the UID:
-
-- Right-click on the [Microsoft Learn](/) page for a type or member, select **View source**, and then copy the **content** value for **ms.assetid**:
-
-  ![ms.assetid in source for web page](media/how-to-write-links/ms-assetid.png)
-
-- Use the [autocomplete site][] by appending some or all of the name of the type to the URL. For example, entering `https://xref.docs.microsoft.com/autocomplete?text=Writeline` in the address bar of your browser displays all the types and methods that contain **Writeline** in their name, along with their UID.
-
-#### Verify the UID
-
-To test if you have the correct UID, replace **System.String** in the following URL with your UID, and then paste it into the address bar of a browser:
-
-`https://xref.docs.microsoft.com/query?uid=System.String`
-
-> [!TIP]
-> The UID in the URL is case-sensitive, and if you're checking a method overload UID, don't include spaces between the parameter types.
-
-If you see something like the following, you have the correct UID:
-
-```text
-[{"uid":"System.String","name":"String","fullName":"System.String","href":"https://learn.microsoft.com/dotnet/api/system.string","tags":",/dotnet,netframework-4.5.1,netframework-4.5.2,netframework-4.5,...xamarinmac-3.0,public,","vendor":null,"hash":null,"commentId":"T:System.String","nameWithType":"System.String"},{"uid":"System.String","name":"String","fullName":"System.String","href":"https://learn.microsoft.com/dotnet/api/system.string","tags":",/dotnet,netframework-4.5.1,netframework-4.5.2,netframework-4.5,netframework-4.6,netframework-4.6.1,...,xamarinmac-3.0,public,","vendor":null,"hash":null,"commentId":"T:System.String","nameWithType":"System.String"}]
-```
+The UID is usually the fully qualified class or member name. To determine the UID, right-click on the [Microsoft Learn](/) page for a type or member, select **View source**, and then copy the **content** value for **ms.assetid**.
 
-If you just see `[]` displayed on the page, you have the wrong UID.
+![ms.assetid in source for web page](media/how-to-write-links/ms-assetid.png)
 
 ### Percent-encoding of URLs
 
-Special characters in the UID need to be HTML encoded as follows:
+Special characters in the UID need to be [percent-encoded](https://en.wikipedia.org/wiki/Percent-encoding) as follows:
 
 | Character | HTML encoding |
 | --------- | ------------- |
-| `` ` ``   | %60           |
-| `#`       | %23           |
-| `*`       | %2A           |
-
-See a full list of [percent-codes](https://en.wikipedia.org/wiki/Percent-encoding).
-
-Encoding examples:
+| `*`       | *           |
 
-- ``System.Threading.Tasks.Task`1`` encodes as `System.Threading.Tasks.Task%601` (see the [section on generic types](#generic-types))
+Encoding example:
 
 - `System.Exception.#ctor` encodes as `System.Exception.%23ctor`
 
-- `System.Object.Equals*` encodes as `System.Object.Equals%2A`
-
 ### Generic types
 
 Generic types are those types such as `System.Collections.Generic.List<T>`. If you browse to this type in the [.NET API browser](/dotnet/api/) and look at its URL, you see that `<T>` is written as `-1` in the URL, which actually represents **`1**:
 
 `https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1`
 
-To link to a generic type such as **List\<T>**, encode the **\`** backtick character as **%60**, as
-shown in the following example:
-
-```markdown
-<xref:System.Collections.Generic.List%601>
-```
-
 ### Methods
 
-To link to a method, you can either link to the general method page by adding an asterisk (`*`) after the method name, or to a specific overload. For example, use the general page when you want to link to the `<xref:System.Object.Equals%2A?displayProperty=nameWithType>` method without specific parameter types. The asterisk character is encoded as `%2A`. For example:
+To link to a method, you can either link to the general method page by adding an asterisk (`*`) after the method name, or to a specific overload. For example, use the general page when you want to link to the `<xref:System.Object.Equals*?displayProperty=nameWithType>` method without specific parameter types. For example:
 
-`<xref:System.Object.Equals%2a?displayProperty=nameWithType>` links to <xref:System.Object.Equals%2A?displayProperty=nameWithType>
+`<xref:System.Object.Equals*?displayProperty=nameWithType>` links to <xref:System.Object.Equals*?displayProperty=nameWithType>
 
 To link to a specific overload, add parenthesis after the method name and include the full type name of each parameter. Do not put a space character between the type names or the link won't work. For example:
 

diff --git a/Contribute/content/provide-feedback.md b/Contribute/content/provide-feedback.md
@@ -72,37 +72,6 @@ The open-source feedback experience allows open-source communities to use GitHub
 
 To open a GitHub issue, you must have a GitHub account. For more information, see [Create GitHub issues](how-to-create-github-issues.md).
 
-Currently, the open-source experience is enabled for the following repositories:
-
-- Azure/azure-docs-sdk-dotnet
-- Azure/azure-docs-sdk-java
-- dotnet/AspNetCore.Docs
-- dotnet/docs
-- dotnet/docs-aspire
-- dotnet/docs-desktop
-- dotnet/docs-maui
-- dotnet/entityframework.apidocs
-- dotnet/entityframework.docs
-- dotnet/maui-api-docs
-- MicrosoftDocs/azure-docs-powershell
-- MicrosoftDocs/azure-docs-sdk-node
-- MicrosoftDocs/azure-docs-sdk-python
-- MicrosoftDocs/community-content
-- MicrosoftDocs/microsoft-365-community
-- MicrosoftDocs/PowerShell-Docs
-- MicrosoftDocs/PowerShell-Docs-DSC
-- MicrosoftDocs/PowerShell-Docs-Modules
-- MicrosoftDocs/PowerShell-Docs-PSGet
-- MicrosoftDocs/terminal
-- MicrosoftDocs/Windows-Dev-Docs
-- MicrosoftDocs/WSL
-- Mono/SkiaSharp-API-docs
-- OfficeDev/office-js-docs-pr
-- OfficeDev/office-js-docs-reference
-- OfficeDev/office-scripts-docs
-- OfficeDev/office-scripts-docs-reference
-- Xamarin/essentials
-
 ## Related content
 
 - [Edit documentation in the browser](how-to-write-quick-edits.md)
diff --git a/ai-navigator/TOC.yml b/ai-navigator/TOC.yml
@@ -0,0 +1,2 @@
+- name: Artificial Intelligence (AI) skills navigator
+  href: index.yml
diff --git a/ai-navigator/breadcrumb/toc.yml b/ai-navigator/breadcrumb/toc.yml
@@ -0,0 +1,4 @@
+items:
+- name: Artificial Intelligence
+  tocHref: /ai/
+  topicHref: /ai
diff --git a/ai-navigator/docfx.json b/ai-navigator/docfx.json
@@ -10,6 +10,8 @@
           "**/obj/**",
           "**/includes/**",
           "_themes/**",
+          "_themes.pdf/**",
+
           "**/docfx.json",
           "_repo.en-us/**",
           "README.md",
@@ -30,6 +32,9 @@
           "**/obj/**",
           "**/includes/**",
           "_themes/**",
+
+          "_themes.pdf/**",
+
           "**/docfx.json",
           "_repo.en-us/**"
         ]
@@ -38,11 +43,14 @@
     "overwrite": [],
     "externalReference": [],
     "globalMetadata": {
-      "breadcrumb_path": "~/breadcrumb/ai-navigator/toc.yml",
+
+      "breadcrumb_path": "/ai/breadcrumb/toc.json",
       "feedback_system": "Standard",
-      "permissioned-type": "public"
+      "permissioned-type": "public",
+      "uhfHeaderId": "ai"
     },
     "fileMetadata": {},
-    "template": []
+    "template": [],
+    "dest": "ai-navigator"
   }
-}
+}
diff --git a/ai-navigator/index.yml b/ai-navigator/index.yml
@@ -0,0 +1,42 @@
+### YamlMime:FAQ
+metadata:
+  title: "AI Skills Navigator: FAQ"
+  description: "A Frequently Asked Questions (FAQ) page for the AI Skills Navigator."
+  author: bmackinney
+  ms.author: miriam.brady
+  ms.service: artificial-intelligence
+  ms.topic: faq #Don't change.
+  ms.date: 10/03/2024
+
+title: "AI Skills Navigator: FAQ"
+
+sections:
+  - name: What is the AI Skills Navigator?
+    questions:
+      - question: What is the AI Skills Navigator?
+        answer: |
+          The Skills for Social Impact team is building an AI Skills Navigator, an AI assistant designed to direct learners to learning pathways and resources. Users will provide information about their role, expertise level and what they are interested in learning and the navigator will recommend learning pathways. Alternatively, there will be an option to simply ask the AI Skills Navigator a question and it will leverage the skilling pathways and resources it has in its data set to respond or recommend learning.
+
+      - question: What can the AI Skills Navigator do?
+        answer: |
+          The AI Skills Navigator, through AI technology, surfaces answers to questions and suggested learning paths based on input from a learner. These are based on a library of learning paths developed by Microsoft and its partners.
+
+      - question: What is/are the AI Skills Navigator’s intended use(s)?
+        answer: |
+          The intended use of the AI Skills Navigator is to surface learning paths or information from those learning paths that are most relevant to the learner based on their input with the intention to help the learner gain skills in AI. This is done through an AI-powered assistant.
+
+      - question: How was the AI Skills Navigator evaluated? What metrics are used to measure performance?
+        answer: |
+          The AI Skills Navigator has been tested manually and evaluated qualitatively by multiple human testers and subject matter experts, both inside and outside the organization. All grounding data is publicly available and vetted by a Microsoft content team. More evaluation was performed over custom datasets for offensive and malicious prompts (user questions) and responses. In addition, the AI Skills Navigator is continuously evaluated by human testers to ensure it continues to perform at expected levels.
+
+      - question: What are the limitations of the AI Skills Navigator? How can users minimize the impact of the AI Skills Navigator’s limitations when using the system?
+        answer: |
+          The AI Skills Navigator is focused on surfacing resources for gaining AI skills. Therefore, users should focus their questions to the AI assistant on that subject area. It will not be able to answer questions related to other subject areas.
+
+      - question: What operational factors and settings allow for effective and responsible use of the AI Skills Navigator?
+        answer: |
+          The system does not allow customization. Users should leverage their browser settings to ensure the best experience for this site and others.
+
+      - question: What data is collected by the AI Skills Navigator?
+        answer: |
+          The only data collected by the AI Skills Navigator is the information users enter into the chatbot. This data is used for training for the AI and will not be used for any other purpose.