Skip to content

Updating ms.topic for AI readiness #46448

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.

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 5 commits into
base: main
Choose a base branch
from

Conversation

nathlaroche
Copy link

@nathlaroche nathlaroche commented May 27, 2025

Summary

Phase 1 of updating ms.topic as discussed with @BillWagner.


Internal previews

Toggle expand/collapse
📄 File 🔗 Preview link
docs/ai/azure-ai-services-authentication.md Azure AI services authentication and authorization using .NET
docs/azure/azure-tools.md Additional Tools for Azure Developers
docs/azure/configure-visual-studio.md Configure Visual Studio for Azure development with .NET
docs/azure/configure-vs-code.md Configure Visual Studio Code for Azure development with .NET
docs/azure/create-azure-account.md Create an Azure account
docs/azure/dotnet-dev-env-checklist.md docs/azure/dotnet-dev-env-checklist
docs/azure/install-azure-cli.md Install the Azure CLI
docs/azure/key-azure-services.md Key Azure Services for .NET developers
docs/azure/migration/app-service.md Migrate your .NET web app or service to Azure App Service
docs/azure/migration/appcat/app-code-assessment-toolkit.md docs/azure/migration/appcat/app-code-assessment-toolkit
docs/azure/migration/appcat/custom-configuration.md How to customize analysis using run configs
docs/azure/migration/appcat/dotnet-cli.md Analyze applications with the .NET CLI
docs/azure/migration/appcat/faq.md Azure Migrate application and code assessment for .NET FAQ
docs/azure/migration/appcat/install.md Install Azure Migrate application and code assessment for .NET
docs/azure/migration/appcat/interpret-results.md Interpret the analysis results
docs/azure/migration/appcat/visual-studio-copilot.md docs/azure/migration/appcat/visual-studio-copilot
docs/azure/migration/appcat/visual-studio.md Analyze applications with Visual Studio
docs/azure/sdk/aspnetcore-guidance.md Best practices for using the Azure SDK with ASP.NET Core
docs/azure/sdk/authentication/best-practices.md Authentication best practices with the Azure Identity library for .NET
docs/azure/sdk/authentication/credential-chains.md docs/azure/sdk/authentication/credential-chains
docs/azure/sdk/authentication/index.md Authenticate .NET apps to Azure services using the Azure Identity library
docs/azure/sdk/azure-sdk-for-dotnet.md Azure SDK for .NET Overview
docs/azure/sdk/configure-proxy.md Configure a proxy when using the Azure SDK for .NET
docs/azure/sdk/protocol-convenience-methods.md [System.ClientModel exceptions](https://review.learn.microsoft.com/en-us/dotnet/azure/sdk/protocol-convenience-methods?branch=pr-en-us-46448)
docs/core/compatibility/api-removal.md docs/core/compatibility/api-removal
docs/core/compatibility/breaking-changes.md Breaking changes in .NET
docs/core/compatibility/categories.md Compatibility
docs/core/compatibility/library-change-rules.md Change rules for compatibility
docs/core/diagnostics/observability-applicationinsights.md docs/core/diagnostics/observability-applicationinsights
docs/core/diagnostics/observability-otlp-example.md Example: Use OpenTelemetry with OTLP and the standalone Aspire Dashboard

Note

This table shows preview links for the 30 files with the most changes. For preview links for other files in this PR, select OpenPublishing.Build Details within checks.

docfx.json Outdated
"docs/framework/configure-apps/file-schema/**/**.md": "reference",
"docs/framework/data/adonet/ef/language-reference/*-entity-sql.md": "language-reference",
"docs/framework/data/adonet/ef/language-reference/*.md": "language-reference",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why was the -entity-sql dropped here?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To follow the pattern on line 275 and to prevent updates to individual files. But I can bring it back to the previous value if you prefer.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it was done purposely that way because not all the files are actually reference type articles. Example: https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/ef/language-reference/how-to-call-canonical-functions

docfx.json Outdated
@@ -255,7 +255,10 @@
"_csharplang/**/*.md": "language-reference",
"_csharpstandard/**/*.md": "language-reference",
"_vblang/spec/*.md": "language-reference",
"docs/azure/**/**.md": "conceptual",
"docs/architecture/**/*.md": "concept-article",
"docs/azure/**/**.md": "article",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not needed since it's the default, correct? (Here and in a few other places.)

Copy link
Author

@nathlaroche nathlaroche May 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. I will remove any pattern that sets the ms.topic value to article in fileMetadata section.

@nathlaroche
Copy link
Author

@dotnet-policy-service agree company="Microsoft"

Copy link
Member

@BillWagner BillWagner left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @nathlaroche

I went through and added a lot of suggestions on changes to either article or concept-article. In general, those articles that are less likely to be "fresh" were set to the default of article. Newer updates that should be using the latest standard topic types and templates are set to concept-article.

Once you accept the suggestions and address the merge conflicts, this is ready.

"docs/csharp/getting-started/**/*.md": "overview",
"docs/csharp/how-to/**/*.md": "how-to",
"docs/csharp/language-reference/**/*.md": "language-reference",
"docs/csharp/language-reference/compiler-messages/*.md": "error-reference",
"docs/csharp/linq/*.md": "how-to",
"docs/csharp/misc/*.md": "error-reference",
"docs/csharp/programming-guide/**": "conceptual",
"docs/csharp/programming-guide/**": "concept-article",
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Because this is largely stale content that's being slowly updated, let's change this one to "article":

Suggested change
"docs/csharp/programming-guide/**": "concept-article",
"docs/csharp/programming-guide/**": "article",

@@ -3,7 +3,7 @@ title: API removal in .NET
titleSuffix: ""
description: Learn about .NET's policy for obsoleting and removing APIs.
ms.date: 04/27/2023
ms.topic: conceptual
ms.topic: concept-article
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should probably be article:

Suggested change
ms.topic: concept-article
ms.topic: article

@@ -2,7 +2,7 @@
title: .NET breaking changes reference
description: Learn how to navigate the .NET breaking changes reference.
ms.date: 12/22/2022
ms.topic: conceptual
ms.topic: concept-article
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same:

Suggested change
ms.topic: concept-article
ms.topic: article

@@ -2,7 +2,7 @@
description: "Learn more about: Miscellaneous Constructs in Regular Expressions"
title: "Miscellaneous Constructs in Regular Expressions"
ms.date: "03/30/2017"
ms.topic: conceptual
ms.topic: concept-article
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ms.topic: concept-article
ms.topic: article

@@ -2,7 +2,7 @@
title: "Convert strings to types"
description: Understand string parsing in .NET. Parsing converts a string representing a .NET base type into that base type. Parsing is the reverse operation to formatting.
ms.date: "03/30/2017"
ms.topic: conceptual
ms.topic: concept-article
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ms.topic: concept-article
ms.topic: article

@@ -1,7 +1,7 @@
---
title: "Substitutions in Regular Expressions"
description: Make substitutions to replace matched text using regular expressions in .NET. Substitutions are language elements recognized only within replacement patterns.
ms.topic: conceptual
ms.topic: concept-article
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ms.topic: concept-article
ms.topic: article

@@ -1,7 +1,7 @@
---
title: "The Regular Expression Object Model"
description: Review the regular expression object model in .NET. Work with the regular expression engine, & objects & collections related to matching, grouping, & capturing.
ms.topic: conceptual
ms.topic: concept-article
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ms.topic: concept-article
ms.topic: article

@@ -1,7 +1,7 @@
---
title: "Type Conversion in .NET"
description: Read about type conversion in .NET, which creates a value in a new type that's equivalent to the old type's value, but may not keep the original's identity.
ms.topic: conceptual
ms.topic: concept-article
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
ms.topic: concept-article
ms.topic: article

@BillWagner BillWagner self-assigned this Jun 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants