diff --git a/README.md b/README.md
index 6d7618d8..cba403aa 100644
--- a/README.md
+++ b/README.md
@@ -48,6 +48,7 @@ like with a normal installation and default settings:
   - [Gaps Between Segments](#gaps-between-segments)
 - [Meta](#meta)
   - [Kudos](#kudos)
+  - [Developing](#developing)
   - [Contributions / Bugs / Contact](#contributions--bugs--contact)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -414,6 +415,11 @@ This theme wouldn't have happened without inspiration from the original [agnoste
 
 Before creating this theme, I also tried [jeremyFreeAgent's theme](https://github.com/jeremyFreeAgent/oh-my-zsh-powerline-theme) and [maverick2000's theme, ZSH2000](https://github.com/maverick2000/zsh2000).
 
+#### Developing
+
+Documentation for developers is kept on the [Powerlevel9k Github
+wiki](https://github.com/bhilburn/powerlevel9k/wiki/Developers'-Guide).
+
 #### Contributions / Bugs / Contact
 
 If you have any requests or bug reports, please use the tracker in this Github
@@ -423,4 +429,3 @@ I'm happy to accept code contributions from anyone who has a bug fix, new featur
 
 If you would like to contact me directly, you can find my e-mail address on my
 [Github profile page](https://github.com/bhilburn).
-
diff --git a/powerlevel9k.zsh-theme b/powerlevel9k.zsh-theme
index 60386eb2..ddfdc023 100644
--- a/powerlevel9k.zsh-theme
+++ b/powerlevel9k.zsh-theme
@@ -244,8 +244,13 @@ fi
 ################################################################
 
 # Begin a left prompt segment
-# Takes two arguments, background and foreground. Both can be omitted,
-# rendering default background/foreground.
+# Takes four arguments:
+#   * $1: Name of the function that was orginally invoked (mandatory).
+#         Necessary, to make the dynamic color-overwrite mechanism work.
+#   * $2: Background color
+#   * $3: Foreground color
+#   * $4: The segment content
+# The latter three can be omitted,
 left_prompt_segment() {
   # Overwrite given background-color by user defined variable for this segment.
   # We get as first Parameter the function name, which called this function. 
@@ -288,9 +293,13 @@ left_prompt_end() {
 }
 
 # Begin a right prompt segment
-# Takes two arguments, background and foreground. Both can be omitted,
-# rendering default background/foreground. No ending for the right prompt
-# segment is needed (unlike the left prompt, above).
+# Takes four arguments:
+#   * $1: Name of the function that was orginally invoked (mandatory).
+#         Necessary, to make the dynamic color-overwrite mechanism work.
+#   * $2: Background color
+#   * $3: Foreground color
+#   * $4: The segment content
+# No ending for the right prompt segment is needed (unlike the left prompt, above).
 right_prompt_segment() {
   # Overwrite given background-color by user defined variable for this segment.
   local BACKGROUND_USER_VARIABLE=POWERLEVEL9K_${(U)1#prompt_}_BACKGROUND