New chapter: Languages with docs

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

@@ -22,6 +22,7 @@ template = "section-contentless.html"
 		* [Documentation Is A Love Letter To Your Future Self](document-it)
 		* [The Function Documentation Is Its Contract](document-is-contract)
 		* [If A Function Description Includes An "And", It's Wrong](document-and)
+		* [Good Languages Come With Integrated Documentation](languages-docs)
 	* Writing code
 		* [Be Ready To Throw Your Code Away](throw-away)
 		* [Future Thinking Is Future Trashing](future-trashing)

content/books/things-i-learnt/boolean-parameters/index.md

@@ -29,4 +29,4 @@ interface to the outside of your class/module will still be clear.
 
 But _don't_ add flags/Boolean parameters to your functions.
 
-{{ 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/interfaces-changes", next_chapter_title="Beware of Interface Changes") }}
+{{ 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/interface-changes", next_chapter_title="Beware of Interface Changes") }}

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

@@ -29,4 +29,4 @@ called one, you now will need to call two. If your preferred language have
 support for function composition, you can use that to group both functions
 again.
 
-{{ chapters(prev_chapter_link="/books/things-i-learnt/document-is-contract", prev_chapter_title="The Function Documentation Is Its Contract", next_chapter_link="/books/things-i-learnt/throw-away", next_chapter_title="Be Ready To Throw Your Code Away") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/document-is-contract", prev_chapter_title="The Function Documentation Is Its Contract", next_chapter_link="/books/things-i-learnt/language-docs", next_chapter_title="Good Languages Come With Integrated Documentation") }}

content/books/things-i-learnt/languages-docs/index.md

@@ -0,0 +1,38 @@
++++
+title = "Things I Learnt The Hard Way - Good Languages Come With Integrated Documentation"
+date = 2019-06-23
+
+[taxonomies]
+tags = ["en-au", "books", "things i learnt", "languages", "documentation"]
++++
+
+If you're worried about learning some new programming language, you can bet
+the one with a better documentation is the one that is _born_ with a document
+processor.
+
+Same goes for the frameworks/libraries of that language.
+
+<!-- more -->
+
+The answer for that is the same as [languages that come with
+tests](languages-tests): because the programming language standard library
+comes with a documentation generator or even because documentation is bundled
+in the language itself, it reduces the friction needed to start writing the
+documentation.
+
+Python is a curious case that it came with a simple documentation generator
+(PyDoc) and a bundled documentation format (DocStrings). Nowadays, almost
+nobody is using the default documentation generator anymore, but because the
+documentation format is still there and is still supported by the language
+(documentation appears as a property of every function, class and module),
+other tools took the post of default documentation generator, but the
+documentation format is still heavy used.
+
+Also, the opposite seems almost always true: If the language doesn't come with
+integrated documentation, there is a very good chance that the documentation
+or the language or frameworks and libraries will be bad. Or, in the very
+least, every library will pick its own format, every framework will pick its
+own format and they will never match the language format, and you'll end up
+with a mess of a documentation to decipher.
+
+{{ chapters(prev_chapter_link="/books/things-i-learnt/document-and", prev_chapter_title="If A Function Description Includes An And, It's Wrong", next_chapter_link="/books/things-i-learnt/throw-away", next_chapter_title="Be Ready To Throw Your Code Away") }}

content/books/things-i-learnt/throw-away/index.md

@@ -35,4 +35,4 @@ solves the problem, but also the tests for that code.
 ... unless you focus mostly on [integration
 tests](/books/things-i-learnt/integration-tests).
 
-{{ chapters(prev_chapter_link="/books/things-i-learnt/document-and", prev_chapter_title="If A Function Description Includes An And, It's Wrong", next_chapter_link="/books/things-i-learnt/future-trashing", next_chapter_title="Future Thinking Is Future Trashing") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/languages-docs", prev_chapter_title="Good Languages Come With Integrated Documentation", next_chapter_link="/books/things-i-learnt/future-trashing", next_chapter_title="Future Thinking Is Future Trashing") }}