docs(rome_diagnostics): Move Writing Diagnostics to the top
MODIFY
crates/rome_diagnostics/CONTRIBUTING.md
crates/rome_diagnostics/CONTRIBUTING.md
@@ -9,6 +9,29 @@ understand for the final user.
## What is a Diagnostic
+Diagnostics are at the core of the experience of the Rome toolchain for the
+users, and providing high quality diagnostics is crucial to making the usage of
+Rome as frictionless as possible even when errors happen. What follows is a
+list of best practice for writing good diagnostics:
+
+- The Diagnostic should follow the [Technical Principles](https://rome.tools/#technical)
+of the Rome project
+- A diagnostic should not simply state that something went wrong, it should
+ explain why it went wrong. Add explanations in log advices, and show hyperlinks
+ to relevant documentation pages in case the user wants to know more.
+- If possible, a diagnostic should also try to provide a way for the user to
+ fix the issue. This can be in the form of a simple log advice, as a diff advice
+ for a source code change, or as a command advice to prompt the user for a
+ direct action. In any case, don't forget to add the `FIXABLE` tag to the
+ diagnostic to highlight to the user it contains an actionable hint.
+- Show don't tell: while log advices are highly versatile, always prefer
+ showing a rich advice like a code frame, diff or command to a textual
+ explanation if you can, since those are generally easier to understand and may
+ provide additional context.
+
+
+## The `Diagnostic` trait
+
At the lowest level, `Diagnostic` is a Rust trait implemented by various types
across the codebase that each represent a specific kind of diagnostic. All
these types have the following properties in common, as enforced by the trait:
@@ -117,24 +140,3 @@ The category may also require some special care if you're declaring a new one,
since all diagnostic categories have to be statically registered you'll need to
add it to `crates/rome_diagnostics_categories/src/categories.rs`
-## Writing a Diagnostic
-
-Diagnostics are at the core of the experience of the Rome toolchain for the
-users, and providing high quality diagnostics is crucial to making the usage of
-Rome as frictionless as possible even when errors happen. What follows is a
-list of best practice for writing good diagnostics:
-
-- The Diagnostic should follow the (Technical Principles)[https://rome.tools/#technical]
-of the Rome project
-- A diagnostic should not simply state that something went wrong, it should
-explain why it went wrong. Add explanations in log advices, and show hyperlinks
-to relevant documentation pages in case the user wants to know more.
-- If possible, a diagnostic should also try to provide a way for the user to
-fix the issue. This can be in the form of a simple log advice, as a diff advice
-for a source code change, or as a command advice to prompt the user for a
-direct action. In any case, don't forget to add the `FIXABLE` tag to the
-diagnostic to highlight to the user it contains an actionable hint.
-- Show don't tell: while log advices are highly versatile, always prefer
-showing a rich advice like a code frame, diff or command to a textual
-explanation if you can, since those are generally easier to understand and may
-provide additional context.

docs(rome_diagnostics): Move Writing Diagnostics to the top (#3551)