Add a note on the style for diagnostic output (rust-lang#2198)

Some contributors are already following this guide regarding diagnostic output style, but this isn't mentioned anywhere.

This PR is more of a proposal to officially adopt these style guidelines. It adds a sentence noting this and linking to the guide itself.

Author: adpaco-aws

docs/src/conventions.md

@@ -70,11 +70,15 @@ Make sure to add user-friendly errors for constructs that we can't handle.
 For example, Kani cannot handle the panic unwind strategy, and it will fail compilation if the crate uses this
 configuration.
 
+In general, it's preferred that error messages follow [these guidelines](https://rustc-dev-guide.rust-lang.org/diagnostics.html#diagnostic-output-style-guide) used for `rustc` development.
+If the errors are being emitted from `kani-compiler`, you should use the compiler error message utilities (e.g., the `Session::span_err` method). However, if the
+errors are being emitted from `kani-driver`, you should use the functions provided in the `util` module in `kani-driver`.
+
 ### Internal compiler errors
 
 Even though this doesn't provide users the best experience, you are encouraged to add checks in the compiler for any
 assumptions you make during development.
-Those check can be on the form of `assert!()` or `unreachable!()`
+Those checks can be on the form of `assert!()` or `unreachable!()`
 statement.
 Please provide a meaningful message to help user understand why something failed, and try to explain, at least with 
 a comment, why this is the case.

kani-driver/src/util.rs

@@ -1,6 +1,15 @@
 // Copyright Kani Contributors
 // SPDX-License-Identifier: Apache-2.0 OR MIT
 
+//! Module that provides functions which are convenient for different purposes.
+//!
+//! In particular, the `warning` and `error` functions must be used for
+//! diagnostic output across the `kani-driver` components. Please follow the
+//! recommendations in <https://model-checking.github.io/kani/conventions.html>
+//! when reporting any kind of diagnostic for users. Note that it's recommended
+//! to use the Rust compiler's error message utilities if you're working on the
+//! `kani-compiler`.
+
 use std::ffi::OsString;
 use std::path::{Path, PathBuf};
 use std::process::Command;