Merge branch 'release/20190701.2'

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

@@ -41,6 +41,8 @@ template = "section-contentless.html"
 		* [Resist The Temptation Of Easy](resist-easy)
 		* [Always Use Timezones With Your Dates](use-timezones)
 		* [Always Use UTF-8 For Your Strings](use-utf8)
+		* [Start Stupid](start-stupid)
+		* [Logs Are For Events, Not User Interface](log-events)
 * Community/Teams
 	* [A Language Is Much More Than A Language](languages-are-more)
 	* [Understand And Stay Away From Cargo Cult](cargo-cult)

content/books/things-i-learnt/languages-are-more/index.md

@@ -39,4 +39,4 @@ surface of what the whole of a language encapsulates and if you ignore the
 other elements in it, you may find yourself with a cute language in a
 community that is always fighting and never going forward.
 
-{{ chapters(prev_chapter_link="/books/things-i-learnt/use-utf8", prev_chapter_title="Always Use UTF-8 For Your Strings", next_chapter_link="/books/things-i-learnt/outside-project", next_chapter_title="Don't Mess With Things Outside Your Project") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/log-events", prev_chapter_title="Logs Are For Events, Not User Interface", next_chapter_link="/books/things-i-learnt/outside-project", next_chapter_title="Don't Mess With Things Outside Your Project") }}

content/books/things-i-learnt/log-events/index.md

@@ -0,0 +1,44 @@
++++
+title = "Things I Learnt The Hard Way - Logs Are For Events, Not User Interface"
+date = 2019-07-01
+
+[taxonomies]
+tags = ["en-au", "books", "things i learnt", "logs", "ui"]
++++
+
+Two things in one: First of all, when using logging, use it to log events, not
+for user interfaces; second, log _events_ in a machine readable way, not
+necessarily an human readable format.
+
+<!-- more -->
+
+For a long time, I used logs to show to the user what was happening. Nothing
+could be the idea of displaying errors, general information and, if the user
+requested, the internals of whatever is going on in one simple way. I mean,
+yeah, let me add the errors, the info messages and the debug messages and let
+the user decide what they want to see.
+
+But that's not what logs are targeted for -- and now I'm having to rethink
+most of the stuff I already wrote.
+
+Use the standard output to inform the user what's going on, in a human
+readable format; use the standard err to inform the user when things go wrong;
+but use the logs to capture something that you'll have to process later, so
+you should probably use a format that it is easier to parse, even if it is not
+so friendly.
+
+As an example, let's say you're connecting to a server. You could use the
+standard output to say "Connecting to server", to give the user a feedback
+about what's going on; at the same time, you could log "CONNECTION
+[SERVER]", with the IP/Name of the server you're connecting. Surely, the
+"CONNECTION" word is not that friendly to the user, but if you had to parse
+the line, it would be really easy, wouldn't it?
+
+Another example: If your application is adding a record to the database, there
+is nothing wrong logging "ADDING_RECORD: field=value; field=value;
+field=value" 'cause, in case something goes wrong while saving the record, you
+could have the values to try to figure out why it failed -- surely, logging
+why it failed also helps, but you know what I mean. This is an example of
+something that makes complete sense in logs, but not in user interfaces.
+
+{{ chapters(prev_chapter_link="/books/things-i-learnt/start-stupid", prev_chapter_title="Start Stupid", next_chapter_link="/books/things-i-learnt/languages-are-more", next_chapter_title="A Language Is Much More Than A Language") }}

content/books/things-i-learnt/start-stupid/index.md

@@ -0,0 +1,33 @@
++++
+title = "Things I Learnt The Hard Way - Start Stupid"
+date = 2019-07-01
+
+[taxonomies]
+tags = ["en-au", "books", "things i learnt", "kiss"]
++++
+
+One way to get away from the IDE is to "start stupid": Just get the compiler
+and get an editor (ANY editor) with code highlight and do your thing: Code,
+build it, run it.
+
+<!-- more -->
+
+Notice that say "stupid way", not "simple way".
+
+Doing things in the stupid way is not the easiest way to start a project. How
+could one beat the easy of clicking a button and having the whole structure of
+a project done for you?
+
+But starting it in the stupid way, in which you have to think your project
+layout, how to build stuff, how to run tests, how to do _everything_ may give
+you some insights on how things work, how the pieces mesh together and how to
+cogs turn around.
+
+Honestly, you don't have to do this with all projects. You can still use your
+favourite IDE and do things in the easy way. But you can also have that side
+project on which you'll do everything in the stupid way, just to understand
+what your IDE is doing.
+
+And when you grasp that, you'll be able to use _any_ IDE.
+
+{{ chapters(prev_chapter_link="/books/things-i-learnt/use-utf8", prev_chapter_title="Always Use UTF-8 For Your Strings", next_chapter_link="/books/things-i-learnt/log-events", next_chapter_title="Logs Are For Events, Not User Interface") }}

content/books/things-i-learnt/use-utf8/index.md

@@ -52,4 +52,4 @@ single character. Walking through the whole string would require traversing
 the string character by character, instead of simply jumping straight to the
 proper position. But that's a price worth paying, in the long run.
 
-{{ chapters(prev_chapter_link="/books/things-i-learnt/use-timezones", prev_chapter_title="Always Use Timezones With Your Dates", next_chapter_link="/books/things-i-learnt/languages-are-more", next_chapter_title="A Language Is Much More Than A Language") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/use-timezones", prev_chapter_title="Always Use Timezones With Your Dates", next_chapter_link="/books/things-i-learnt/start-stupid", next_chapter_title="Start Stupid") }}