From f5ee98e87510907b66bcf0eb7e88973f74e8f98e Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Wed, 19 Jun 2019 09:58:20 -0300 Subject: [PATCH] Added disclaimer and Gherkin chapters --- content/books/things-i-learnt/_index.md | 3 ++ .../books/things-i-learnt/disclaimer/index.md | 42 +++++++++++++++ .../books/things-i-learnt/gherkin/index.md | 54 +++++++++++++++++++ content/books/things-i-learnt/intro/index.md | 2 +- .../books/things-i-learnt/spec-first/index.md | 2 +- .../steps-as-comments/index.md | 2 +- 6 files changed, 102 insertions(+), 3 deletions(-) create mode 100644 content/books/things-i-learnt/disclaimer/index.md create mode 100644 content/books/things-i-learnt/gherkin/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index 8edc99e..cc68ce1 100644 --- a/content/books/things-i-learnt/_index.md +++ b/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) diff --git a/content/books/things-i-learnt/disclaimer/index.md b/content/books/things-i-learnt/disclaimer/index.md new file mode 100644 index 0000000..4281987 --- /dev/null +++ b/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 + + + +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") }} diff --git a/content/books/things-i-learnt/gherkin/index.md b/content/books/things-i-learnt/gherkin/index.md new file mode 100644 index 0000000..39db425 --- /dev/null +++ b/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. + + + +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") }} diff --git a/content/books/things-i-learnt/intro/index.md b/content/books/things-i-learnt/intro/index.md index 30e94e5..138f1fd 100644 --- a/content/books/things-i-learnt/intro/index.md +++ b/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") }} diff --git a/content/books/things-i-learnt/spec-first/index.md b/content/books/things-i-learnt/spec-first/index.md index fda957f..046626c 100644 --- a/content/books/things-i-learnt/spec-first/index.md +++ b/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") }} diff --git a/content/books/things-i-learnt/steps-as-comments/index.md b/content/books/things-i-learnt/steps-as-comments/index.md index d09a7d8..637a12e 100644 --- a/content/books/things-i-learnt/steps-as-comments/index.md +++ b/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") }}