Improve Deprecation Guidelines more (#13776)

* Improve deprecation guidelines more

* prettier

Author: alamb

README.md

@@ -138,10 +138,10 @@ Note: If a Rust hotfix is released for the current MSRV, the MSRV will be update
 
 DataFusion enforces MSRV policy using a [MSRV CI Check](https://github.com/search?q=repo%3Aapache%2Fdatafusion+rust-version+language%3ATOML+path%3A%2F%5ECargo.toml%2F&type=code)
 
-## DataFusion API evolution policy
+## DataFusion API Evolution and Deprecation Guidelines
 
 Public methods in Apache DataFusion evolve over time: while we try to maintain a
 stable API, we also improve the API over time. As a result, we typically
-deprecate methods before removing them, according to the [api health policy].
+deprecate methods before removing them, according to the [deprecation guidelines].
 
-[api health policy]: https://datafusion.apache.org/library-user-guide/api-health.html
+[deprecation guidelines]: https://datafusion.apache.org/library-user-guide/api-health.html

docs/source/library-user-guide/api-health.md

@@ -31,7 +31,7 @@ APIs to give users time to adjust to the changes.
 In general, a function is part of the public API if it appears on the [docs.rs page]
 
 Breaking public API changes are those that _require_ users to change their code
-for it to compile, and are listed as "Major Changes" in the [SemVer
+for it to compile and execute, and are listed as "Major Changes" in the [SemVer
 Compatibility Section of the cargo book]. Common examples of breaking changes:
 
 - Adding new required parameters to a function (`foo(a: i32, b: i32)` -> `foo(a: i32, b: i32, c: i32)`)
@@ -57,11 +57,7 @@ version will be `44.0.0`.
 
 [`cargo.toml`]: https://github.com/apache/datafusion/blob/main/Cargo.toml
 
-To mark the API as deprecated, use the `#[deprecated]` attribute like this:
-
-```rust
-    #[deprecated(since = "...", note = "...")]
-```
+To mark the API as deprecated, use the `#[deprecated(since = "...", note = "...")]` attribute.
 
 For example: