New chapter: Document your code

content/books/things-i-learnt/_index.md

@@ -16,4 +16,5 @@ template = "section-contentless.html"
 	* [Make Tests That You Know How To Run on the Command line](tests-in-the-command-line)
 	* [Be Ready To Throw Your Code Away](throw-away)
 	* [Good Languages Come With Tests](languages-tests)
-	* [Future Think Is Future Trashing](future-trashing)
+	* [Future Thinking Is Future Trashing](future-trashing)
+	* [Documentation Is a Love Letter To Your Future Self](document-it)

content/books/things-i-learnt/document-it/index.md

@@ -0,0 +1,28 @@
++++
+title = "Things I Learnt The Hard Way - Documentation Is a Love Letter To Your Future Self"
+date = 2019-06-21
+
+[taxonomies]
+tags = ["en-au", "books", "things i learnt", "documentation"]
++++
+
+We all know writing the damn docs for functions and classes and modules is a
+pain in the backside. But realizing what you were thinking when you wrote the
+function will save your butt in the future.
+
+<!-- more -->
+
+When I say that it will save your butt, I don't mean the documentation will
+tell you something like "Here are the lotto numbers in 2027"[^1] or "If John
+complains about your future code review, here is some shit he did in the
+past".
+
+I mean, it will explain how the _flow_ of your code is expected to do. Imaging
+this: pick your code and replace every function call to its documentation. Can
+you understand what it is expected by reading that? If you can,
+congratulations, you won't have a problem in the future; if you can't... well,
+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") }}

content/books/things-i-learnt/future-trashing/index.md

@@ -23,4 +23,4 @@ solutions and _then_ you'll find your "solve everything". This pattern is the
 _abstraction_ you're looking for and _then_ you'll be able to solve it in a
 simple way.
 
-{{ chapters(prev_chapter_link="/books/things-i-learnt/languages-tests", prev_chapter_title="Good Languages Come With Tests") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/languages-tests", prev_chapter_title="Good Languages Come With Tests", next_chapter_link="/books/things-i-learnt/document-id", next_chapter_title="Documentation Is a Love Letter To Your Future Self") }}

content/thoughts/things-i-learnt-the-hard-way.md

@@ -171,7 +171,7 @@ you can finally kill the original function.
 function as deprecated and _add a sleep at the start of the function_, in a
 way that people using the old function are forced to update.)
 
-### Good languages come with integration documentation
+### Good languages come with integrated documentation
 
 If the language comes with its own way of documenting
 functions/classes/modules/whatever and it comes even with the simplest doc