diff --git a/builtin.c b/builtin.c
index c1ca26645..6afa9aafb 100644
--- a/builtin.c
+++ b/builtin.c
@@ -3431,7 +3431,7 @@ const static builtin_data_t builtin_data[]=
 	}
 	,
 	{
-		L"breakpoint",  &builtin_breakpoint, N_( L"Temporarily halt execution and launch a new prompt" )  
+		L"breakpoint",  &builtin_breakpoint, N_( L"Temporarily halt execution of a script and launch an interactive debug prompt" )  
 	}
 	,
 
diff --git a/doc_src/breakpoint.txt b/doc_src/breakpoint.txt
new file mode 100644
index 000000000..f3332c755
--- /dev/null
+++ b/doc_src/breakpoint.txt
@@ -0,0 +1,10 @@
+\section breakpoint breakpoint - Launch debug mode
+
+\subsection breakpoint-synopsis Synopsis
+ <tt>breakpoint</tt>
+
+\subsection breakpoint-description Description
+
+The \c breakpoint builtin is used to halt a running script and launch
+an interactive debug prompt.
+
diff --git a/doc_src/index.hdr.in b/doc_src/index.hdr.in
index 6e504114e..53db33c93 100644
--- a/doc_src/index.hdr.in
+++ b/doc_src/index.hdr.in
@@ -1283,6 +1283,20 @@ For more information on how to define new event handlers, see the
 documentation for the <a href='commands.html#function'>function</a>
 command.
 
+\subsection debuging Debuging fish scripts
+
+Fish includes a built in debuger. The debuger allows you to stop
+execution of a script at an arbitrary point and launch a prompt. This
+prompt can then be used to check or change the value of any variables
+or perform any shellscript command. To resume normal execution of the
+script, simply exit the prompt.
+
+To start the debugger, simply call the builtin command
+'breakpoint'. The default action of the TRAP signal is to call this
+builtin, so a running script can be debuged by sending it the TRAP
+signal. Once in the debuger, it is easy to insert new breakpoints by
+using the funced function to edit the definition of a function.
+
 \section issues Common issues with fish
 
 If you install fish in your home directory, fish will not work