Today, some of our source code repos like Runtime, WPF, WinForms and WCF, consider the dotnet-api-docs repo the source of truth for their documentation. This poses some challenges:

• We only use triple slash comments in source for seeding the documentation.
• We have to manually port these comments to dotnet-api-docs so they show up both in MS Docs and in IntelliSense.
• Before the ported comments get merged in dotnet-api-docs, they need to go through language review, which may change the contents considerably.
• Once they get merged, the triple slash comments in source become obsolete.
• We depend on the Docs build system to generate IntelliSense for us with the language-reviewed contents.
• We need to consume the generated IntelliSense in the source code repos via a nuget package to make it available in the published SDK.
• Any documentation changes/fixes need to be done in dotnet-api-docs, which may cause even greater discrepancies with the original triple slash comments, unless the developer also submits a PR to fix the comments there.
• This complex manual process and the dependency round trip made it difficult to ensure APIs introduced in 1.x and 2.x were fully documented in MS Docs and IntelliSense. We improved our process for 3.x and 5.0 and prevented documentation debt in those versions, but we still had to do the whole process manually.
• The fact that dotnet-api-docs shows shared documentation for .NET Core and .NET Framework is one of the main reasons why this process has remained the way it currently is.
• We rarely add code examples to new APIs. The few examples we have, live in dotnet-api-docs. Some of the existing ones use obsolete APIs, or APIs that only exist in .NET Framework, or show old coding conventions.

We would like to propose a series of changes in our documentation process that will simplify the developer's role and automate some of the steps. During .NET 6, we piloted this new documentation process with a subset of the .NET Libraries. That pilot produced the following outputs:

• Overall feasibility and promise of the new process
• An assessment of contributor satisfaction with the new process
• An understanding of the challenges that would need to be overcome across the remaining libraries
• A project plan for either completing the migration or canceling the pilot and reverting to the previous process, with a new User Story created and all involved work estimated

We will continue this plan in .NET 8.

Bring documentation from Docs to triple slash

Substitute all the triple slash comments in source code with the language-reviewed documentation that exists in dotnet-api-docs. We will do this on an assembly by assembly basis, and will enable the MSBuild property <GenerateDocumentationFile> to ensure new public APIs cause a build warning when they don't have documentation.

We will be using the dotnet/api-docs-sync PortToTripleSlash tool for this effort, for which I added the feature to port dotnet-api-docs to triple slash comments: https://github.com/dotnet/api-docs-sync/tree/main/src/PortToTripleSlash

Remarks

We won't backport remarks for the following reasons:

• They are bulky. Really long remarks would have to be moved to external files and linked in the triple slash comments.
• They aren't shown in VS intellisense.
• Remarks usually contain links to code example external files. Files with code snippets will remain in the dotnet-api-docs repo, untouched. When (and if) we backport remarks containing links to those code snippets, the links will be relative to the dotnet-api-docs repo.
• Remarks also contain embedded markdown code snippets. They would have to be moved to their own files and merged directly in dotnet-api-docs, to avoid having huge triple slash comments sections.

.NET Framework-only APIs

APIs that only exist in .NET Framework will continue having dotnet-api-docs as its source of truth.

APIs that are shared by both .NET Core and .NET Framework will have their source of truth in triple slash comments in .NET Core, making sure we preserve the differences in behavior between versions.

Merge blocking label and docs reviewers

We already have a bot task that automatically adds the new-api-needs-documentation label to PRs that are introducing new public APIs, but we want to make sure it also becomes a merge blocker, like the * NO MERGE * label does.

Once the PR has been reviewed by a maintainer, and they confirmed the new APIs have proper documentation, the label can be manually removed to unblock merging.

We also want the bot to automatically add the @dotnet/docs members as PR reviewers for language review.

Automatic Docs build

Note: We can only begin this work if we finished backporting the documentation from all assemblies.

Currently, whenever new APIs are added to the source code repos, we send the updated ref assemblies to the Docs team so they feed them to the Docs build system, which causes the regeneration of the dotnet-api-docs xml files, showing the new APIs. After this point, we can then manually port the documentation from triple slash, using https://github.com/dotnet/api-docs-sync/tree/main/src/PortToTripleSlash

From now on, we want to automate the process by automatically merging the ref assembly drop (it's just a commit in an internal repo). This drop will also contain the build-generated IntelliSense xmls, which would now contain the documentation source of truth, removing the step of manual porting.

Debt prevention and docs fixes

At the time of writing this document, we have 900+ issues open in the dotnet-api-docs repo. We would like to consider these as part of the regular work planning for our dev teams, and we want to make it easier to filter issues by area by automatically adding labels using a bot, and area owners should be notified (on a subscription basis, like in runtime).

Contributors will still be able to report documentation issues in dotnet-api-docs, but fixes will now be done directly in triple slash comments in source. PRs will be disabled in dotnet-api-docs except for maintainers.

Documentation for APIs that only exist .NET Framework will continue to be done directly in dotnet-api-docs (that will be its source of truth).

Low pri / Nice to have

The following are tasks that are out of scope for this effort, but we would like to consider in the near future:

• - Add CI validation to the code snippets in the dotnet-api-docs repo.
• - Redirect the MS Docs Edit button to the source code file instead of the dotnet-api-docs xml file. To achieve this, we would also have to include PDBs in the drop that contains the ref assemblies and xmls, and the Docs team would have to read them to determine the location of the source code for an API.
• - Consider creating a new PR label needs doc update that would also become merge blocking, to ensure documentation gets updated when behavior is changed. Here is a good argument in favor of that.

Questions and suggestions are welcome.