Docs: C# spec links in C# reference should point to specific parts of the spec

[svick]

Many articles in the C# reference contain the following section:

C# Language Specification

For more information, see the C# Language Specification. The language specification is the definitive source for C# syntax and usage.

While that link is useful, even more useful would be a link to the specific part of the specification that talks about the same topic as the article (e.g. the sizeof article would link to Unsafe code, section The sizeof operator), especially since the spec is large and the location of the right section might not be obvious (e.g. the sizeof operator is not specified along with most operators in Expressions, but is instead in Unsafe Code).

I suspect that this wasn't done in the past, because the spec used to be a Word file. But now that it's a subsection of docs.MS, linking to a specific part is easy.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: a60b6e17-36cf-bd6c-1b76-d38f1760a816
• Version Independent ID: 0fdeaa81-c3c2-c290-224e-792fcee9b297
• Content: C# Reference
• Content Source: docs/csharp/language-reference/index.md
• Product: dotnet-csharp
• GitHub Login: @BillWagner
• Microsoft Alias: wiwagn

[rpetrusha]

I agree, @svick; the links should point to a specific part of the spec. I've added this issue to the backlog, as well as to the community contributor's project.

[sujon2100]

Excellent!

[Mackiovello]

I'd be happy to take this one

[svick]

I think this issue should be reopened, since not all instances were fixed.

As far as I can tell, https://github.com/dotnet/docs/pull/8221 did good work by fixing articles that reference the spec directly. But there are still many articles that use [!INCLUDE[CSharplangspec](~/includes/csharplangspec-md.md)] to link to it indirectly. I think those should be improved too.

[pkulikov]

Agree with @svick. These are almost all keyword and operator articles. While I'm going through the operator articles to move snippets to the samples repo, I'll update links to the C# spec as well. So, an update of the keyword articles is up-for-grabs.

[BillWagner]

I also think this is a good idea.

Rather than re-open this issue, I'd like to do the following:

1. Do a quick file search to find all locations with the generic include.
2. Create an issue that requests the following for each file or folder:
   
   
   
   • Add proper deep links into the spec if they are not already present.
   
   
   • Remove the general link, if that's appropriate.
   
   
   • Check off that file in the issue.
   
   

I'd think one PR per folder would be reasonable.

Thoughts on the plan? If you both approve, I'll create the master issue later today. /cc @svick @pkulikov

[pkulikov]

@BillWagner that sounds like a good plan

[svick]

@BillWagner Sounds good to me.