Added disclaimer and Gherkin chapters

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

@@ -5,6 +5,9 @@ template = "section-contentless.html"
 +++
 
 * [Intro](intro)
+* [Disclaimer](disclaimer)
+
 * Programming:
 	* [Spec First, Then Code](spec-first)
 	* [Write Steps as Comments](steps-as-comments)
+	* [Gherkin Is Your Friend to Understand Expectations](gherkin)

content/books/things-i-learnt/disclaimer/index.md

@@ -0,0 +1,42 @@
++++
+title = "Things I Learnt The Hard Way - Disclaimer"
+date = 2019-06-19
+
+[taxonomies]
+tags = ["en-au", "books", "things i learnt", "disclaimer"]
++++
+
+There is one magical thing you need to know when reading this book: It's all
+personal opinion
+
+<!-- more -->
+
+A lot of stuff I'm going to discuss throughout this book will come directly
+from my personal experience in several projects -- system applications, web
+backend, embedded, mobile, stream processing -- in several different languages
+-- C, C++, Python, Java. And, because it comes from personal experience,
+everything reflects my own personal opinion on several subjects.
+
+Obviously, you don't need to agree with every single point.
+
+Also, sometimes I may mention some examples that people who know me -- either
+worked with me, heard me complain about some project, inherit one of my
+projects, _I_ inherit one of the _their_ projects -- may recognized and think
+I'm attacking the author.
+
+I am not.
+
+We do mistakes. Sometimes we don't know the topic with are attacking,
+sometimes we don't have full specs, sometimes we don't have the time to write
+things properly in a crunchtime. And that's why some things don't look as
+pretty as they should. Heck, if you think I'm attacking the original author of
+some example, look back the stuff I wrote and you'll see things a lot worse.
+
+But I need the example. I want to show people how things can be better. I want
+to show people how my opinion built over some subject. And, again, I'm in no
+way attacking the original author of the code. I may even call the code
+"stupid", but I'm not calling the author _stupid_.
+
+With that in mind...
+
+{{ chapters(prev_chapter_link="/books/things-i-learnt/intro", prev_chapter_title = "Intro", next_chapter_link="/books/things-i-learnt/spec-first", next_chapter_title="Spec First, The Code") }}

content/books/things-i-learnt/gherkin/index.md

@@ -0,0 +1,54 @@
++++
+title = "Things I Learnt The Hard Way - Gherkin Is Your Friend to Understand Expectations"
+date = 2019-06-19
+
+[taxonomies]
+tags = ["en-au", "book", "things i learnt", "gherkin", "expectations"]
++++
+
+Gherkin is file format for writing behaviour tests. But it can also give you
+some insights on what you should do.
+
+<!-- more -->
+
+Alright, let's talk a bit about Gherkin:
+
+[Gherkin](https://en.wikipedia.org/wiki/Cucumber_(software)#Gherkin_language)
+is a file format created for [Cucumber](https://en.wikipedia.org/wiki/Cucumber_(software)),
+which describes scenarios, what's in them, what actions the user/system will
+do and what's expected after those actions, in a very high level, so people
+without programming experience can describe what's expected from the system.
+
+Although Gherkin was born with Cucumber, it is now supported by a bunch of
+programming languages, through external libraries.
+
+A typical Gherkin file may look something like this:
+
+* **Given that** _initial system environment_
+* **When** _action performed by the user or some external system_
+* **Then** _expected system environment_
+
+Or, in a more concrete example:
+
+* **Given that** The system is retrieving all tweets favourited by the user
+* **When** It finds a tweet with an attachment
+* **Then** The attachment should be saved along the tweet text
+
+Pretty simple, right?
+
+Now, why I'm mentioning this?
+
+Sometimes, specs are not the most clear source of information about what it is
+expected from the system. If you're confused about what you should write,
+asking the person responsible for the request to write something like Gherkin
+may give you some better insights about it.
+
+Obviously, it won't be complete. People tend to forget the error situations --
+people entering just numbers on names, letter in age fields, tweets with no
+text and just attachments -- but at least with a Gherkin description of the
+system, you can get a better picture of the whole.
+
+Also, you may not like to write specs. That's alright, you can replace them
+with Gherkin anyway.
+
+{{ chapters(prev_chapter_link="/books/things-i-learnt/steps-as-comments", prev_chapter_title="Write Steps as Comments") }}

content/books/things-i-learnt/intro/index.md

@@ -49,4 +49,4 @@ technology after 30 years. So... thread carefully, 'cause here be dragons.
 
 [^1]: Yup, I'm guilty of that too.
 
-{{ chapters(next_chapter_link="/books/things-i-learnt/spec-first", next_chapter_title="Spec First, The Code") }}
+{{ chapters(next_chapter_link="/books/things-i-learnt/disclaimer", next_chapter_title="Disclaimer") }}

content/books/things-i-learnt/spec-first/index.md

@@ -37,4 +37,4 @@ kind of stuff -- "I don't know what to do next, and I'm not sure if I'm done
 with the current problem" -- then maybe it's time to stop and talk to other
 people in the project to figure that out.
 
-{{ chapters(prev_chapter_link="/books/things-i-learnt/intro", prev_chapter_title="Intro", next_chapter_link="/books/things-i-learnt/steps-as-comments", next_chapter_title="Write Steps as Comments") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/disclaimer", prev_chapter_title="Disclaimer", next_chapter_link="/books/things-i-learnt/steps-as-comments", next_chapter_title="Write Steps as Comments") }}

content/books/things-i-learnt/steps-as-comments/index.md

@@ -55,4 +55,4 @@ main code.
 
 [^1]: Yes, that was sarcastic.
 
-{{ chapters(prev_chapter_link="/books/things-i-learnt/spec-first", prev_chapter_title="Specs First, Then Code") }}
+{{ chapters(prev_chapter_link="/books/things-i-learnt/spec-first", prev_chapter_title="Specs First, Then Code", next_chapter_link="/books/things-i-learnt/gherkin", next_chapter_title="Gherkin Is Your Friend to Understand Expectations") }}