diff --git a/modules/ui/hl-todo/README.org b/modules/ui/hl-todo/README.org
index d8af7eb85..15e62368a 100644
--- a/modules/ui/hl-todo/README.org
+++ b/modules/ui/hl-todo/README.org
@@ -1,13 +1,79 @@
 #+TITLE: :ui hl-todo
 
-This module adds syntax highlighting for TODO/FIXME/NOTE tags in programming major-modes.
+* Table of Contents :TOC_3:noexport:
+- [[#description][Description]]
+  - [[#module-flags][Module Flags]]
+  - [[#plugins][Plugins]]
+- [[#prerequisites][Prerequisites]]
+- [[#features][Features]]
+  - [[#making-items][Making Items]]
+  - [[#using-items][Using Items]]
+- [[#configuration][Configuration]]
+- [[#troubleshooting][Troubleshooting]]
 
-What keywords are highlighted (and their color) can be customized through ~hl-todo-keyword-faces~.
+* Description
+This module adds syntax highlighting for TODO/FIXME/NOTE tags in programming
+major-modes.
 
-#+BEGIN_SRC emacs-lisp
+** Module Flags
+This module provides no flags
+** Plugins
+[[https://github.com/tarius/hl-todo][hl-todo]]
+* Prerequisites
+This module has no prerequisites
+* Features
+** Making Items
+You can make a TODO item by simply writing
++ =TODO=
+  For things that need to be done, just not today.
++ =HACK=
+  For tidbits that are unconventional and not intended uses of the
+  constituent parts, and may break in a future update.
++ =FIXME=
+  For problems that will become bigger problems later if not fixed ASAP.
++ =REVIEW=
+  for things that were done hastily and/or hasn't been thoroughly
+  tested. it may not even be necessary!
++ =NOTE=
+  For especially important gotchas with a given implementation,
+  directed at another user other than the author.
++ =DEPRECATED=
+  For things that just gotta go and will soon be gone.
++ =BUG=
+  For a known bug that needs a workaround
++ =XXX=
+  For warning about a problematic or misguiding code
+** Using Items
+To see all of the TODO items in a project you can use
+=SPC p t=
+This will bring up a buffer you can use to quickly jump to the item
+* Configuration
+To add your own ITEMS you would need to configure them using
+~hl-todo-keyword-faces~
+#+BEGIN_SRC emacs-lisp :tangle no
 ;; the default
 (setq hl-todo-keyword-faces
-      `(("TODO"  . ,(face-foreground 'warning))
-        ("FIXME" . ,(face-foreground 'error))
-        ("NOTE"  . ,(face-foreground 'success))))
+      `(("FOO"  . ,(face-foreground "MY COLOUR HEX CODE"))
+        ("BAR" . ,(face-foreground 'my-colour-var))))
 #+END_SRC
+
+You can also add keybindings to jump and configure the next TODO item in the buffer using
+| function           | description                       | proposed binding |
+|--------------------+-----------------------------------+------------------|
+| ~hl-todo-previous~ | move to the last TODO item        | =C-c t p=        |
+| ~hl-todo-next~     | move to the next TODO item        | =C-c t n=        |
+| ~hl-todo-occur~    | list all TODO items in the buffer | =C-c t o=        |
+| ~hl-todo-insert~   | make a new TODO item              | =C-c t i=        |
+
+this can be mapped like this
+#+BEGIN_SRC emacs-lisp :tangle no
+(map! :prefix "C-c t"
+    "p"#'hl-todo-previous
+    "n"#'hl-todo-next
+    "o"#'hl-todo-occur
+    "i"#'hl-todo-insert)
+
+#+END_SRC
+
+* Troubleshooting
+If you have any problems with this module do get in touch!