Converted a few more chapters

things-i-learnt/src/SUMMARY.md

@@ -6,3 +6,5 @@
 	- [Before You Start Writing Code](./programming/before.md)
 		- [Spec First, Then Code](./programming/spec-first.md)
 		- [Write Steps as Comments](./programming/steps-as-comments.md)
+		- [Gherkin Is Your Friend to Understand Expectations](./programming/gherkin.md)
+		- [Design Patters Are Used to Name Solution, Not Find Them](./programming/patterns-not-solutions.md)

things-i-learnt/src/programming/gherkin.md

@@ -0,0 +1,46 @@
+# Gherkin Is Your Friend to Understand Expectations
+
+Gherkin is file format for writing behaviour tests (BDD). 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, allowing
+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 liked 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, and up can't think of [steps to do
+so](/books/things-i-learnt/steps-as-comments). 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 --
+like filling the name field with numbers, using characters 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.

things-i-learnt/src/programming/patterns-not-solutions.md

@@ -0,0 +1,28 @@
+# Design Patterns Are Used to Name Solution, Not Find Them
+
+Most of the times I saw design patterns being applied, they were applied as a
+way to find a solution, so you end up twisting a solution -- and, sometimes,
+the problem it self -- to fit the pattern.
+
+My guess is that the heavy use of "let's apply _this_ design pattern" before
+even understanding the problem -- or even trying to solve it -- comes as a
+form of [cargo cult](/books/things-i-learnt/cargo-cult): "We saw that people
+used this pattern and solved their problem, so let's use it too and it will
+solve our problem". Or, worse: "Design pattern is described by _Famous
+Person_, so we must use it".
+
+Here is the thing: Design pattern should _not_ be used as a way to find
+solution to any problems. You may use some of them as base for your solution,
+but you must focus on the _problem_, not the _pattern_. 
+
+"Do a visitor pattern will solve this?" is the wrong question. "What should we
+do to solve our problem?" is the real question. Once you went there and solved
+the problem you may look back and see if it is a visitor pattern -- or whatever
+pattern. If it doesn't, that's alright, 'cause you _solved the problem_. If it
+did... well, congratulations, you now know how to name your solution.
+
+I've seen this happening a lot: People have a problem; people decided to use a
+pattern; the pattern doesn't actually solve the problem (not in the 100% mark,
+but above 50%); what happens then is that people start twisting the problem to
+fit the pattern or, worse, add new layers to transform the problem into the
+pattern.

things-i-learnt/src/programming/spec-first.md

@@ -1 +1,41 @@
 # Spec First, Then Code
+
+"Without requirements or design, programming is the art of adding bugs to an
+empty text file." -- Louis Srygley
+
+If you don't know what you're trying to solve, you don't know what to code.
+
+A lot of times we have this feeling of "let me jump straight to the code". But
+without understanding what problem you're trying to solve, you'd end up
+writing a bunch of things that doesn't solve anything -- or, at least,
+anything that _should_ be solved.
+
+So here is the point: Try to get a small spec on whatever you want to solve.
+But be aware that even that spec may have to be [thrown
+out](/books/things-i-learnt/throw-away), as the understanding of the problem
+tend to grow as long as the project continue.
+
+Yes, it's paradoxical: You need a spec to know what to code to avoid coding
+the wrong solution, but the spec may be wrong, so you _end up_ solving the
+wrong solution anyway. So what's the point? The point is, the spec reflects
+the understanding of a problem _at a certain point_: All you (and your team)
+know is _there_.
+
+The times I stood longer looking at my own code wondering what to do next were
+when we didn't have the next step defined: It was missing some point of the
+solution or we didn't have the communication structures defined or something
+of sorts. Usually, when that happened, I stumbled upon Twitter or Mastodon
+instead of trying to solve the problem. So when you see yourself doing this
+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.
+
+Another way to think this: Erik Deitrich have a post about [Don’t Learn to
+Code — Learn to Automate](https://daedtech.com/dont-learn-to-code-learn-to-automate/),
+something I can get behind 'cause most of us, when doing stuff, think "I need
+to do this, then I pick that thingy and put it there and from there I do this
+other work". Basically, we create mental models of specs, step by step, on
+what we need to do. And, from there, it may be even simpler, 'cause now all
+you need to learn is "First, how I do this; Ok, got it, now I get the result
+from this and put there" and so on. You can even have a learning path, if
+you're a beginner.