diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
index baff6ba..b6aa9ed 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -8,7 +8,7 @@ assignees: ''
 ---
 
 **Check troubleshooting**
-Please first check [TROUBLESHOOTING.md](https://github.com/almindor/mipidsi/blob/master/docs/TROUBLESHOOTING.md) to ensure your issue is not solved there already.
+Before submitting a new issue, please check the [troubleshooting guide](https://github.com/almindor/mipidsi/blob/master/docs/TROUBLESHOOTING.md) to make sure it hasn't already been addressed there.
 
 **Describe the bug**
 A clear and concise description of what the bug is.
@@ -22,8 +22,13 @@ A clear and concise description of what you expected to happen.
 **Screenshots**
 If applicable, add screenshots to help explain your problem.
 
-**MCU and Display model**
-Please provide specific MCU and display model used
+**Used hardware and software**
+Please provide details about the hardware and software you are using:
+- `mipidsi` version: e.g. latest `master` or `0.9.1`
+- MCU: e.g. ESP32S3
+- HAL: e.g. esp_hal 0.23.1
+- Display Controller IC: e.g. ILI9341
+- Type of connection: e.g. SPI
 
 **Additional context**
 Add any other context about the problem here.
diff --git a/README.md b/README.md
index ced19e1..3200e1e 100644
--- a/README.md
+++ b/README.md
@@ -45,16 +45,11 @@ Variants that require different screen sizes and window addressing offsets are n
 - ST7789
 - ST7796
 
-## Migration
-
-See [MIGRATION.md](../docs/MIGRATION.md) document.
-
-
 ## Troubleshooting
 
-See [TROUBLESHOOTING.md](https://github.com/almindor/mipidsi/blob/master/docs/TROUBLESHOOTING.md) if you're having issues with blank screen or incorrect colors showing up.
+Refer to the [troubleshooting guide](https://github.com/almindor/mipidsi/blob/master/docs/TROUBLESHOOTING.md) if you experience problems like a blank screen or incorrect colors.
 
-### Example
+## Example
 
 ```rust
 // create a DisplayInterface from SPI and DC pin, with no manual CS control
@@ -66,6 +61,9 @@ let mut display = Builder::new(ILI9486Rgb666, di)
 // clear the display to black
 display.clear(Rgb666::BLACK)?;
 ```
+## Migration
+
+See [MIGRATION.md](../docs/MIGRATION.md) document.
 
 ## Minimum Supported Rust Version (MSRV)
 
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 8130497..56aefe3 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -1,4 +1,6 @@
-# Display troubleshooting
+# Troubleshooting guide
+
+This guide lists common issues that can cause a blank or corrupted display.
 
 ## Display stays black/blank
 
diff --git a/src/lib.rs b/src/lib.rs
index 0027c3d..7ef86b1 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -27,10 +27,12 @@
 //! * ST7796
 //!
 //! ## Troubleshooting
-//! See [TROUBLESHOOTING.md](https://github.com/almindor/mipidsi/blob/master/docs/TROUBLESHOOTING.md) if you're having
-//! issues with blank screen or incorrect colors showing up.
+//!
+//! Refer to the [troubleshooting guide](https://github.com/almindor/mipidsi/blob/master/docs/TROUBLESHOOTING.md)
+//! if you experience problems like a blank screen or incorrect colors.
 //!
 //! ## Examples
+//!
 //! **For the ili9486 display, using the SPI interface with no chip select:**
 //! ```
 //! use mipidsi::interface::SpiInterface;                    // Provides the builder for DisplayInterface