New chapter: Logs for events

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

@@ -42,6 +42,7 @@ template = "section-contentless.html"
 		* [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/start-stupid", prev_chapter_title="Start Stupid", 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

@@ -30,4 +30,4 @@ 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/languages-are-more", next_chapter_title="A Language Is Much More Than A Language") }}
+{{ 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") }}