diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md
index 8372f7f..6f2249e 100644
--- a/content/books/things-i-learnt/_index.md
+++ b/content/books/things-i-learnt/_index.md
@@ -18,3 +18,4 @@ template = "section-contentless.html"
 	* [Good Languages Come With Tests](languages-tests)
 	* [Future Thinking Is Future Trashing](future-trashing)
 	* [Documentation Is a Love Letter To Your Future Self](document-it)
+	* [The Function Documentation Is Its Contract](document-is-contract)
diff --git a/content/books/things-i-learnt/document-is-contract/index.md b/content/books/things-i-learnt/document-is-contract/index.md
new file mode 100644
index 0000000..9c02812
--- /dev/null
+++ b/content/books/things-i-learnt/document-is-contract/index.md
@@ -0,0 +1,37 @@
++++
+title = "Things I Learnt The Hard Way - The Function Documentation Is Its Contract"
+date = 2019-06-21
+
+[taxonomies]
+tags = ["en-au", "books", "things i learnt", "documentation", "contracts"]
++++
+
+When you start the code by [writing the
+documentation](/books/things-i-learnt/steps-as-comments), you're actually
+making a contract (probably with your future self): I'm saying this function
+does _this_ and _this_ is what it does.
+
+<!-- more -->
+
+Remember that the documentation must be a clear explanation of what your code
+_is_ doing; remember that good messages will make [reading the code only by
+the function documentation](/books/things-i-learnt/document-id) should be
+clear.
+
+A function called `mult`, documented as "Get the value and multiply by 2" but,
+when you look at the code, it does multiply by 2, but sends the result through
+the network or even just asks a remote service to multiply the incoming result
+by 2, is clearly breaking its contract. It's not just multiplying by 2, it's
+doing more than just that, or it's asking someone else to manipulate the
+value.
+
+Now, what happens when this kind of thing happens?
+
+The easy solution is to change the documentation. But do you know if people
+who called the function expecting it to be "multiply value by 2" will be happy
+for it to call an external service? There is a clear breach of "contract" --
+whatever you initially said your function would do -- so the correct solution
+would be to add a new function with a proper contract -- and probably a better
+name.
+
+{{ chapters(prev_chapter_link="/books/things-i-learnt/document-it", prev_chapter_title="Documentation Is a Love Letter To Your Future Self") }}
diff --git a/content/books/things-i-learnt/document-it/index.md b/content/books/things-i-learnt/document-it/index.md
index 7203d5f..fe34aa0 100644
--- a/content/books/things-i-learnt/document-it/index.md
+++ b/content/books/things-i-learnt/document-it/index.md
@@ -25,4 +25,4 @@ I have some bad news for you...
 
 [^1]: Please, don't make me revise this in 2027... :(
 
-{{ chapters(prev_chapter_link="/books/things-i-learnt/future-trashing", prev_chapter_title="Future Thinking is Future Trashing") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/future-trashing", prev_chapter_title="Future Thinking is Future Trashing", next_chapter_link="/books/things-i-learnt/document-is-contract", next_chapter_title="The Function Documentation Is Its Contract") }}