From 79034daa8fb53dac99b462e2735fec8ec2176d36 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Sun, 23 Jun 2019 18:17:19 -0300 Subject: [PATCH] New chapter: Languages with docs --- content/books/things-i-learnt/_index.md | 1 + .../boolean-parameters/index.md | 2 +- .../things-i-learnt/document-and/index.md | 2 +- .../things-i-learnt/languages-docs/index.md | 38 +++++++++++++++++++ .../books/things-i-learnt/throw-away/index.md | 2 +- 5 files changed, 42 insertions(+), 3 deletions(-) create mode 100644 content/books/things-i-learnt/languages-docs/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index 382c95f..73bb354 100644 --- a/content/books/things-i-learnt/_index.md +++ b/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) diff --git a/content/books/things-i-learnt/boolean-parameters/index.md b/content/books/things-i-learnt/boolean-parameters/index.md index 7819692..fea0c77 100644 --- a/content/books/things-i-learnt/boolean-parameters/index.md +++ b/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") }} diff --git a/content/books/things-i-learnt/document-and/index.md b/content/books/things-i-learnt/document-and/index.md index 8938adb..e63f271 100644 --- a/content/books/things-i-learnt/document-and/index.md +++ b/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") }} diff --git a/content/books/things-i-learnt/languages-docs/index.md b/content/books/things-i-learnt/languages-docs/index.md new file mode 100644 index 0000000..aab2705 --- /dev/null +++ b/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. + + + +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") }} diff --git a/content/books/things-i-learnt/throw-away/index.md b/content/books/things-i-learnt/throw-away/index.md index c684409..62ebab8 100644 --- a/content/books/things-i-learnt/throw-away/index.md +++ b/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") }}