☂ [Tracking] Restructure diagnostic message docs

MaryaBelanger commented 1 year ago

There are a lot of small inconsistencies across the diagnostic messages documentation that altogether make the topic's content appear disjointed. For example,

The way lint messages are written varies slightly from message to message.
They differ completely from diagnostic messages, despite really just being two different types of the same thing.
Lints docs are built on two separate sites and tools link to each.
And other related maintenance issues.

Goal: Restructure the diagnostic message documentation to be more consistent, across messages, pages, and sites.

This issue is for planning/tracking. Most of the points can be addressed asynchronously. Some of the relevant content and the work described lives outside of this repo.

1. Consolidate linter rules with other diagnostic messages

Decision: TBD / Needs input

Issue: https://github.com/dart-lang/site-www/issues/4498

2. Consistent format and information across diagnostic messages

Decision: Rewrite individual linter rules to match diagnostic message format

Issue: https://github.com/dart-lang/linter/issues/3924

The diagnostic messages have a more exact/succinct format to them than the lint messages, so we'll rewrite the lint messages to match that syntax.

This means using the structure of:

Single line summary
Description
Example
Common fixes (instead of GOOD/BAD)

Also need to standardize other features of lint messages not included in diagnostic messages:

How we link to Effective Dart
"This rule is available as of...."
"Rule sets:..."
"Quick fix available..."

@atsansone I know you had ideas about restructuring or standardizing the layout of individual messages, if you want to share here

3. Deprecate github.io/linter

Decision: repoint all the tools to dart.dev/tools/linter-rules and BE CAREFUL WITH REDIRECTS

Hosting the lint docs on github.io was decided before the linter rules were added to dart.dev. Now that they're on dart.dev (where they should be, to keep docs in one place), the io page should be deprecated.

A lot of tools point to the io pages though, so the redirects need to be dealt with very carefully.

4. Update how to enable lint instructions

Decision: page hasn't been reviewed in a while, make sure it's up to date

https://dart.dev/guides/language/analysis-options

5. Create guidance page for which lints to use

Decision: Add a page to the static analysis set of pages that provides guidance on which lints to enable for your needs

This will go into detail on the existing common lint sets, and maybe other use cases.

Recreate this page in dart.dev that groups lints by purpose: https://dart-lang.github.io/linter/lints/index.html

6. Standardize process for contributing lint messages

Decision: Document the exact format we decide on for linter rules, and a plan for how they are reviewed

Being addressed here:

Trial for reviewing in CLs: https://dart-review.googlesource.com/c/sdk/+/278640

7. Misc. improvements to diagnostic messages

Decision: pros and cons / benefit vs. cost of each of these needs further evaluation

Adding labels / icons / some other indicators to message docs that indicate things like:

Whether the lint has a quick fix (linter rules have it, diagnostic does not)
For lints, if it has any incompatible lints
If the lint belongs to a package/set, and if so, which one
What type of diagnostic it is (lint, error, warning)
Having a bug report per message in the docs, so users can report whether they found a lint helpful or it did what they expected

8. (Tangential) Consolidate type promotion error pages

Slightly related to diagnostic messages because some link to Type promotion failures page

Issue: https://github.com/dart-lang/site-www/issues/4393

9. (Tangential) Use the diagnostics glossary as a starting point for a standard site-wide glossary

The Glossary section on the Diagnostic messages page has a wealth of information that is really applicable to the site as a whole. We've discussed taking that content out and putting it on a new page (already created, https://dart.dev/resources/glossary). This would require all the links in the diagnostic and linter docs be updated to point to the same sections on the new page.

Issue: #4622

@bwilkerson @pq

bwilkerson commented 1 year ago

Consistent format and information across diagnostic messages

Single line summary

The existing diagnostic messages don't actually have a single line summary, what appears to be a summary is actually the message that's displayed to users in the IDE. We have it there to assure users that they've found the correct documentation.

I'll note, however, that the IDEs also display a correction message (when there is one; not all diagnostics have such a message), which isn't displayed on these pages. The reason it's not displayed is because it's usually a subset of the possible fix options discussed under "Common fixes".

Standardize process for contributing lint messages

Trial for reviewing in CLs: https://dart-review.googlesource.com/c/sdk/+/278640

That particular CL is related to the non-lint diagnostic messages, though I suppose that the same process can, and should, be used for both kinds of messages.

Misc. improvements to diagnostic messages

Whether the lint has a quick fix (linter rules have it, diagnostic does not)

That's not accurate. Many lints have quick fixes, but not all of them do, and non-lint diagnostics sometimes have quick fixes, though it's a smaller percentage than for lints.

parlough commented 1 year ago

Wasn't sure which issue to post this in, but I continued a discussion on page length and multiple pages here: https://github.com/dart-lang/site-www/issues/4498#issuecomment-1376065655

Since it sounds like it is expected to mostly only visit diagnostic messages from tooling and IDEs, perhaps it doesn't make sense to have such a long page. We're already having users leave their workflow to visit a site and serving a bunch of information when they likely won't be manually scrolling for other diagnostics doesn't make a lot of sense.

I'm not too concerned about page clutter, especially since we could generate the diagnostic pages as part of the build process from some YAML or JSON structure. Perhaps we could even serve Markdown files too so IDEs could surface the documentation inline (are they capable of that?).

MaryaBelanger commented 1 year ago

Thanks @bwilkerson, I'll update all these details up top.

That's not accurate. Many lints have quick fixes....

I think what I meant was the non-lint diagnostic message docs don't mention if they have a quick fix or not, but some of the lint docs do (is that accurate? quick ctrl+f "quick fix" on diagnostic-messages shows nothing). I'll update that at the top, thanks for pointing out.

That particular CL is related to the non-lint diagnostic messages...

I also think the same process should eventually be used for both. Like the format of the messages themselves, I think it makes sense to standardize work around the non-lint messages (already very standardized), and then integrate those practices into lint work (as much as possible with the more variant nature of lints)

@parlough I was expecting that conversation to be pretty active so I broke it out, but once a decision is reached I'll update up top with the conclusion. I think as work actually starts for each of these items, they'll probably all warrant their own issues!

bwilkerson commented 1 year ago

I think what I meant was the non-lint diagnostic message docs don't mention if they have a quick fix or not, ...

That's correct.

... but some of the lint docs do ...

All of the lints that have a quick fix associated with them have a badge that indicates that fact. If there's no badge then it's because there's no fix. (The badges are programmatically added so that they can't be out of date.)

atsansone commented 1 year ago

Check these issues to be sure you capture everything: https://github.com/dart-lang/site-www/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc+label%3Adiagnostics

dart-lang / site-www