diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst
index 2829cee7bc..34ee392d25 100644
--- a/docs/troubleshooting.rst
+++ b/docs/troubleshooting.rst
@@ -1,21 +1,25 @@
 Troubleshooting
-==============================
+===============
 
 From time to time, an error occurs when working with CircuitPython. Here are a
 variety of errors that can happen, what they mean and how to fix them.
 
 File system issues
-------------------------------
+------------------
 
-If your host computer starts complaining that your CIRCUITPY drive is corrupted
+If your host computer starts complaining that your ``CIRCUITPY`` drive is corrupted
 or files cannot be overwritten or deleted, then you will have to erase it completely.
-When CircuitPython restarts it will create a fresh empty CIRCUITPY filesystem.
+When CircuitPython restarts it will create a fresh empty ``CIRCUITPY`` filesystem.
 
-This often happens on Windows when the CIRCUITPY disk is not safely ejected
+This often happens on Windows when the ``CIRCUITPY`` disk is not safely ejected
 before being reset by the button or being disconnected from USB. This can also
 happen on Linux and Mac OSX but its less likely.
 
-.. danger:: This will erase all your files in CIRCUITPY!
+.. caution:: Delete ``CIRCUITPY`` filesystem and reload CircuitPython.
+
+    To reload CircuitPython (for example, to correct a corrupted filesystem),
+    follow the process below. It's important to note that **any files stored on the
+    ``CIRCUITPY`` drive will be erased**.
 
 #. Download the appropriate flash erase uf2 from `here <https://github.com/adafruit/Adafruit_SPIFlash/tree/master/examples/flash_erase_express>`_.
 #. Double-click the reset button.
@@ -24,17 +28,18 @@ happen on Linux and Mac OSX but its less likely.
 #. After about 15 seconds, the NexoPixel will start flashing green. If it flashes red, the erase failed.
 #. Double-click again and load the appropriate `CircuitPython .uf2 <https://github.com/adafruit/circuitpython/releases/latest>`_.
 
-ValueError: Incompatible .mpy file.
--------------------------------------
+ValueError: Incompatible ``.mpy`` file.
+---------------------------------------
 
-This error occurs when importing a module that is stored as a `mpy` binary file
-(rather than a `py` text file) that was generated by a different version of
+This error occurs when importing a module that is stored as a ``mpy`` binary file
+(rather than a ``py`` text file) that was generated by a different version of
 CircuitPython than the one its being loaded into. Most versions are compatible
-but, rarely they aren't. In particular, the `mpy` binary format changed between
+but, rarely they aren't. In particular, the ``mpy`` binary format changed between
 CircuitPython versions 1.x and 2.x.
 
-So, if you just upgraded to 2.x from 1.x you'll need to download a newer version
-of the library. They are all available in the
+So, if you just upgraded to CircuitPython 2.x from 1.x you'll need to download a
+newer version of the library that triggered the error on ``import``. They are
+all available in the
 `Adafruit bundle <https://github.com/adafruit/Adafruit_CircuitPython_Bundle/releases/latest>`_
 and the `Community bundle <https://github.com/adafruit/CircuitPython_Community_Bundle/releases/latest>`_.
 Make sure to download a version with 2.0.0 or higher in the filename.