dotnet / dotnet/docs

Simplify compiler messages content

Open
#24,002 8 comments 0 reactions 0 assignees View on GitHub
discussion dotnet-csharp/svc errors-warnings/subsvc
Dominant language
No language data
Stars
4.8k
Forks
6.1k
Avg merge
15h 21m
Merged PRs (30d)
370

Description

There are several large issues in the content that covers [C# Compiler messages](https://docs.microsoft.com/dotnet/csharp/language-reference/compiler-messages/).

1. Many errors and warnings are not documented. (More than 700 have already been identified [here](https://github.com/dotnet/docs/blame/main/docs/csharp/misc/sorry-we-don-t-have-specifics-on-this-csharp-error.md#L6-L736)).
1. There are 623 individual articles that do cover existing errors and warnings. That many different warnings and errors make this content hard to navigate.
1. The purpose of these articles is to help developers modify their code so it compiles without errors or warnings. That makes this content rather important: developers are effectively blocked when they reach these pages.

Can we reorganize this material around types of errors and warnings into a (somewhat) smaller set of articles that help developers diagnose and fix related issues in their code?

A good starting point is to look at the organization in the [C# Error codes](https://github.com/dotnet/roslyn/blob/main/src/Compilers/CSharp/Portable/Errors/ErrorCode.cs) in the [dotnet/roslyn](https://github.com/dotnet/roslyn) repository. For newer versions (starting with C# 5), the first digit of the code indicates the version when the error or warning was introduced. Further, those messages are often organized by feature:
- C# 5 warnings are in the range 4000-4999
- C# 6 is in the range 5000-5999, 7000-7999 and 8000-8106
- C# 7 is in the range 8107-8210 and are organized by feature.
- C# 7.1 is in the range 8300-8315
- C# 7.2 is in the range 8320-8364 and are organized by feature.
- C# 7.3 is in 8370-8389
- C# 8 is in 8400-8750, and organized by feature
- C# 9 is in the range 8751-8911
- C# 10 (in progress) starts at 8912

- C# 5 warnings and errors are almost all about [`async` and `await`](https://github.com/dotnet/roslyn/blob/main/src/Compilers/CSharp/Portable/Errors/ErrorCode.cs#L1103-L1141).
- C# 6 is a mixture of errors and warnings for the features introduced in that version. [These](https://github.com/dotnet/roslyn/blob/main/src/Compilers/CSharp/Portable/Errors/ErrorCode.cs#L1254-LL1341) could be organized by feature.
- Errors and warnings for features added after 6 are generally organized by feature. This provides a potential roadmap for a new organization for pages organized around each feature.

One major concern to this plan is how to organize articles for errors and warnings introduced before C# 5. When I scanned the list, two groups stand out: LINQ and dynamic. I can spot some related to generics or partial methods, they aren't groups that way.

Before beginning these changes we need to create a full plan for which errors and warnings would be included in each new article.

***Proposed article format***

If the concern can be addressed, I propose organizing each article on the following outline:

- **Feature or Subsystem area**
- Table of errors, including code and message
- A few examples of the correct syntax and uses for the features
- Links to relevant language reference articles
- Links to relevant C# spec sections

***SEO Concerns***

The existing articles have been optimized for each error code and message. The title, H1, and description all include the error and message. Those techniques raise these articles visibility in search for the error code. That may be hard to replicate in a more simplified presentation. Possible actions:

- F1 keywords will help developers using Visual Studio.
- The table of errors and messages should help as well.
- Redirection from existing content should help inherit some of the search rank.

More work here should be done before we begin. If we follow this plan, the new pages should rank in the first page for any relevant compiler error or warning code.

---
#### Document Details

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

* ID: fc586192-534e-0108-d265-c4f2f6947c57
* Version Independent ID: 4d39f536-5d78-335b-3525-d4b581c28fdc
* Content: [C# Compiler messages](https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-messages/)
* Content Source: [docs/csharp/language-reference/compiler-messages/index.md](https://github.com/dotnet/docs/blob/main/docs/csharp/language-reference/compiler-messages/index.md)
* Product: **dotnet-csharp**
* Technology: **csharp-diagnostics**
* GitHub Login: @BillWagner
* Microsoft Alias: **wiwagn**

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.