Document IO Error (#6712)

`IOError` is special, it is not actually a lint but an error before
linting. I'm not entirely sure how to document it since it does not
match the general lint rule pattern (`Checks that the file can be read
in its entirety.` is imho worse).

I added the in my experience two most common reasons for io errors on
unix systems and linked two tutorials on how to fix them.

See https://github.com/astral-sh/ruff/issues/2646

---------

Co-authored-by: Charlie Marsh <charlie.r.marsh@gmail.com>

crates/ruff/src/rules/pycodestyle/rules/errors.rs

@@ -7,6 +7,28 @@ use ruff_source_file::Locator;
 
 use crate::logging::DisplayParseErrorType;
 
+/// ## What it does
+/// This is not a regular diagnostic; instead, it's raised when a file cannot be read
+/// from disk.
+///
+/// ## Why is this bad?
+/// An `IOError` indicates an error in the development setup. For example, the user may
+/// not have permissions to read a given file, or the filesystem may contain a broken
+/// symlink.
+///
+/// ## Example
+/// On Linux or macOS:
+/// ```shell
+/// $ echo 'print("hello world!")' > a.py
+/// $ chmod 000 a.py
+/// $ ruff a.py
+/// a.py:1:1: E902 Permission denied (os error 13)
+/// Found 1 error.
+/// ```
+///
+/// ## References
+/// - [UNIX Permissions introduction](https://mason.gmu.edu/~montecin/UNIXpermiss.htm)
+/// - [Command Line Basics: Symbolic Links](https://www.digitalocean.com/community/tutorials/workflow-symbolic-links)
 #[violation]
 pub struct IOError {
     pub message: String,