diff --git a/docs/faq/README.md b/docs/faq/README.md
index 2b2db7cd..eef2de68 100644
--- a/docs/faq/README.md
+++ b/docs/faq/README.md
@@ -56,11 +56,53 @@ If you get an error like "_version 'GLIBC_2.18' not found (required by starship)
 sh -c "$(curl -fsSL https://starship.rs/install.sh)" -- --platform unknown-linux-musl
 ```
 
+## Why do I see `Executing command "..." timed out.` warnings?
+
+Starship executes different commands to get information to display in the
+prompt, for example the version of a program or the current git status. To make
+sure starship doesn't hang while trying to execute these commands we set a time
+limit, if a command takes longer than this limit starship will stop the
+execution of the command and output the above warning, this is expected
+behaviour. This time limit is configurable using the [`command_timeout`
+key](/config/#prompt) so if you want you can increase the time limit. You can
+also follow the debugging steps below to see which command is being slow and
+see if you can optimise it. Finally you can set the `STARSHIP_LOG` env var to
+`error` to hide these warnings.
+
 ## I see symbols I don't understand or expect, what do they mean?
 
 If you see symbols that you don't recognise you can use `starship explain` to
 explain the currently showing modules.
 
+## Starship is doing something unexpected, how can I debug it?
+
+You can enable the debug logs by using the `STARSHIP_LOG` env var. These logs
+can be very verbose so it is often useful to use the `module` command if you are
+trying to debug a particular module, for example, if you are trying to debug
+the `rust` module you could run the following command to get the trace
+logs and output from the module.
+
+```sh
+env STARHIP_LOG=trace starship module rust
+```
+
+If starship is being slow you can try using the `timings` command to see if
+there is a particular module or command that to blame.
+
+```sh
+env STARHIP_LOG=trace starship timings
+```
+
+This will output the trace log and a breakdown of all modules that either took
+more than 1ms to execute or produced some output.
+
+Finally if you find a bug you can use the `bug-report` command to create a
+Github issue.
+
+```sh
+starship bug-report
+```
+
 ## Why don't I see a glyph symbol in my prompt?
 
 The most common cause of this is system misconfiguration. Some Linux distros in