First steps converting "Things I Learnt" into mdBook

things-i-learnt/.gitignore

@@ -0,0 +1 @@
+book

things-i-learnt/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Julio Biason"]
+language = "en"
+multilingual = false
+src = "src"
+title = "Things I Learnt The Hard Way (In 30 Years of Software Development)"

things-i-learnt/src/SUMMARY.md

@@ -0,0 +1,8 @@
+# Summary
+
+- [Intro](./intro.md)
+- [Disclaimer](./disclaimer.md)
+- [Programming](./programming/index.md)
+	- [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)

things-i-learnt/src/disclaimer.md

@@ -0,0 +1,34 @@
+# 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, Clojure, Rust. 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. But I hope at
+least it will make you rethink a few subjects.
+
+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 have this hope that showing people a few mistakes
+can make things 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...

things-i-learnt/src/intro.md

@@ -0,0 +1,50 @@
+# Intro
+
+"Things I Learnt The Hard Way (In 30 Years of Software Development)" started
+as a simple sequence of toots (the same as "tweets", on
+[Mastodon](https://functional.cafe/@juliobiason) when I was thinking about a
+new presentation I could do.
+
+But why "a new presentation"?
+
+I go around my state with a group called
+"[Tchelinux](https://tchelinux.org/)": We usually go to universities and talk
+to people starting uni, explaining things about free/libre software and
+sometimes telling people about things they wouldn't normally see in the uni
+curriculum.
+
+One thing that annoys me is that there are very few presentations about "when
+things go wrong". All the presentations show prototypes or tell the good
+stuff, and hide all the wrong things that could happen[^1]. Obviously, after
+working 30 years in the field of software development, I saw my fair share of
+things going wrong -- sometimes in unimaginable piles of crap -- and I thought
+"maybe that's something people would like to hear".
+
+(And, to be completely honest, some of those piles of crap were my own fault.)
+
+And that's when the toot sequence started. Just before I noticed, I spent the
+whole day just posting this kind of stuff (fortunately, my pile of things in
+the "incoming" folder was a bit empty at the time) and it had 30 points, plus
+addenda and a few explanation points. That's when I decided to group all
+them in a single post.
+
+(Actually, I'm lying: Someone mentioned on Functional Café that I should make
+a blog post for making it easier to read.)
+
+All I thought when I grouped everything in a post was "this will make things
+easier for the people following the thread on Mastodon". But then the post
+appeared on Reddit. And Twitter. And HackerNews. And YCombinator. And none of
+those where mine.
+
+But here is the thing: Each point was limited by the toot size, which is 500
+characters. Sometimes that's not enough to expand the point, explain it
+properly and add some examples.
+
+And that's how the idea to write this "book" came to life.
+
+One thing you must keep in mind here: *These are my options*. I understand
+that not everything is so black and white as put here, and some people's
+experiences may not match things here. Also, you get a bit cynical about
+technology after 30 years. So... thread carefully, 'cause here be dragons.
+
+[^1]: Yup, I'm guilty of that too.

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

@@ -0,0 +1,4 @@
+# Before You Start Writing Code
+
+Before you sit in front of your computer and open your text editor/IDE to
+write code, maybe you should take a step back and come with some stuff.

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

@@ -0,0 +1,4 @@
+# Programming Tips
+
+I'm a software developer. I write code. So here are some of things I learnt
+about the craft.

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

@@ -0,0 +1 @@
+# Spec First, Then Code

things-i-learnt/src/programming/steps-as-comments.md

@@ -0,0 +1,49 @@
+# Write Steps as Comments
+
+Don't know how to solve your problem? Write the steps as comments in your
+code.
+
+There you are, looking at the blank file wondering how you're going to solve
+that problem. Here is a tip:
+
+Take the spec you (or someone else) wrote. Break each point into a series of
+steps to reach the expected behaviour. You can even write on your natural
+language, if you don't speak English.
+
+Then fill the spaces between the comments with code.
+
+For example, if you have a spec of "connect to server X and retrieve
+everything there. Save the content in the database. Remember that server X API
+allow you can pass an ID (the last ID seen) and you can use it to not retrieve
+the same content again." Pretty simple, right?
+
+Writing this as comments, pointing the steps you need to make, you may end up
+with something like this:
+
+```
+// connect to server X
+// retrieve posts
+// send posts to the database
+```
+
+Ah, you forgot the part about the ID. No problem, you just have to add it in
+the proper places -- for example, it doesn't make sense to connect to the
+server before you have the last seen ID:
+
+```
+// open configuration file
+// get value of the last seen ID; if it doesn't exist, it's empty.
+// connect to server X
+// retrieve posts starting at the last seen ID
+// send posts to the database
+// save the last seen ID in the configuration file
+```
+
+Now it is "easy"[^1]: You just add the code after each comment.
+
+A better option is to change the comments into functions and, instead of
+writing the code between the comments, you write the functionality in the
+function themselves and keep a clean view of what your application does in the
+main code.
+
+[^1]: Yes, that was sarcastic.