Kartones Blog

Be the change you want to see in this world

Choose Your Own Adventure - Epub Gamebook

I love reading, and one of the things I enjoyed a lot as a child was reading Choose Your Own Adventure books. Well, technically they are called gamebooks, but as many others I tend to generalize the brand name as the book type. In any case, they were really simple books with branching paths and narratives, often with multiple endings.

I already have an unfinished but working project for building web CYOA readers, but as I really enjoy reading at bed from my Kindle, I wanted to do a little experiment: try to build ebooks that have branching paths and act like a classic gamebook.

The idea is really simple: Each relevant page number (as in "go to page XXX") becomes a chapter, and as ebooks support links as references to chapters (and they are trivial to set even with minimal formats such as Markdown), build the navigation based on chapters.

A quick search, reading a bit about Pandoc and using its official Docker image, and I was able to quickly build something: https://github.com/Kartones/cyoa-epub.

The sample generated in the repository is a very simple ebook with few chapters, but serves as a, introduction tutorial on how the metadata works, how to add a book cover (of course you can also have images at normal pages), how to add a table of contents, and a minimal "adventure" sample that puts to the test the approach.

And it indeed works! Here's an almost final version being tested:

Testing the ebook in my Kindle

I now guess if with some OCR and a bit of text cleaning and processing I could build digital versions of those childhood books... 🤔


Book Review: Ten Arguments For Deleting Your Social Media Accounts Right Now

Review

Ten Arguments for Deleting Your Social Media Accounts Right Now book cover

Title: Ten Arguments for Deleting Your Social Media Accounts Right Now

Author(s): Jaron Lanier

I picked up this book after watching The Social Dilemma from Netflix (highly recommended, by the way) because the author briefly appears in the documentary. After reading the book, which predates Netflix's title, I'd say the film takes more than a few ideas as inspiration from Jaron's book.

The main topic is how private companies and algorithms developed by them (and kept secret) are permanently monitoring us, grabbing our data, and then shaping the window through which we see things inside them. Using an example from the book, everyone who visits Wikipedia (in language X) sees the same content, meanwhile every person who gets a different, "customized" Facebook feed, or a different list of results after a Google search, because the underlying algorithms adapt what we see to the models they have of our behaviours. And those companies, via advertising, are effectively being paid to manipulate those very same behaviours. So the algorithms get tweaked to favour radicalisms, conflicts and mostly negative topics, as they drive more "views", which means more money.

We get multitude of examples of each argument, in fact I really liked that contrary to other titles that simply say sentences without many proofs, here sometimes a single relevant paragraph can easily have three or more footnotes with related researches, news articles and studies.

It is quite blunt, as some arguments like "you are losing your free will" or "social media is making you into an asshole" exemplify. It's also hard against certain political figures and big tech companies, but always with a level of respect and facts that I admire. It would be very easy to write a collection of radical suggestions to induce rage and hate, and instead I found learning about the Theory of Mind, deindividuation effects or the concept of Data as Labor.

One closing sentence that I found interesting, regarding tech giants simply saying that they're sorry when their services are misused: A social media company is in a better position if it doesn’t know what’s going on, because then it makes just as much money, but with less culpability.

A not complex nor long but thought-provoking read, definitely recommended.


PBRR - Pretty Basic RSS Reader

A pet project that I wanted to do since quite a while (to be precise, since Google killed Google Reader) was building my own RSS reader. Most of the free alternatives I've seen online either have too much advertising for my taste (and while I use an Ad-blocker, there's no best way to encourage me to keep it enabled than to flood with ads), or don't fully work, hiding feed errors or applying some unclear caching policies that make posts sometimes take a day or two to appear in the reader.

I also explored using some existing open-source feed readers, but almost everything is either PHP or Go, and while the later would be pretty easy to setup, in the end I had an excuse to play around with Python once again.

The result is PBRR - Pretty Basic RSS Reader, a very simple but working RSS feed. First a screenshot and then I'll give an overview of the (few) things it does and how:

PBRR Screenshot

It is designed with the same principle as a static-site generator: via Python you execute a runner that fetches from an OPML feeds export all feeds, generates a very simple html files and folders structure (based on simple templates), dumps each post as an html, plus the lists of posts, list of sites, etc. Then, using the incredibly useful Unpoly Javascript library performs AJAX calls to render the data without any server-side code (the alternative would have been to use iframes).

Basically, you setup a cron to run for example hourly to regenerate any new feeds, and set your webserver to serve static content (JS, CSS & HTML). And that's all, nothing scales better and runs faster than purely static content :)

It groups sites into categories (if the OPML had them), sends a proper Last-Modified header to be a good feed consumer citizen, and uses localStorage and a few Javascript lines to differentiate sites with new posts from already seen ones.

You can check the source, fork it, etc. at https://github.com/Kartones/pbrr.

I am using it myself so I might enhance or add new features in the future, but this v1.0 serves my needs and, after some fighting with non-standard feeds (there's always a case or two where feedparser library can't help with malformed feeds), works with all but one RSS subscriptions I had.


Course Review: Become a Data Analyst (LinkedIn Learning)

During February I read somewhere that LinkedIn was offering some of their Learning Path course packs for free for a limited time. I gave a look at them, and liked the Become a Data Analyst one, so decided to give it a go.

First of all, a disclaimer: I don't plan to finish the full path, because I mostly wanted theory and generic examples. Learning Tableau, Power BI, Excel and Access is always interesting but not in my radar, so I focused on around 50% of the contents, and that's what this small review is about.

Each course is between 1.5 and 3.5 hours, and in total I think it was around 24h of content.

Course 1: Learning Data Analytics

Very very tied to Microsoft Office suite products. It is basic and introductory, there's some bits of theory here and there, but I'd say 90% is learning to do things in Excel or Access.

Course 2: Data Fluency: Exploring and Describing Data

This one was better in my humble opinion. Gives a general overview of many terms, ways of representing data, techniques to interpret data and graphs...

Represents exactly what I was expecting to find: teaching me the basics, but the meaningful basics.

Course 3: Learning Data Visualization

Another quite interesting item, both regarding data visualization itself as a topic, and regarding some tips & tricks for massaging data to better represent it.

Easily my favourite by the amount of concepts explained, always alongside at least one example.

Parts of the video are old as mention IE7 and the like, but still broadly atemporal.

The others

I'm currently watching a fourth course, Learning Excel: Data Analysis, but this one at a slower pace as I want a generic overview of how to do common operations with a spreadsheets software (be it Microsoft Excel or Google Spreadsheets).

And there are three more courses, with self-explanatory titles:


My Disposable Notebooks

For about a decade I maintain a certain habit: taking notes both at work and when studying/learning. The studies part is obvious, but at work it helps me a lot when I have to repeat something not trivial or infrequently done, or somebody mentions a topic that I remember I wrote about. As I just finished filling a notebook, thought maybe could be somewhat interesting to share my (basic and non-spectacular) method.

Physical notebooks

Apart from the "digital notes", to which I'll come later on this post, at 2017 I started to use simple Moleskine or alike paper notebooks. My writing is terrible but this way I keep a thin thread of "usage" and not totally forget how to write. I also recall reading or hearing somewhere (I think at this course) that writing notes while learning helps to "learn better", that it boosts your retention, probably because of the explicit effort of repeating the things you write down.

My main idea is that the notebooks are disposable, so it's fine if I write in a hurry some gibberish (that I later need to decrypt), or improvise, or jump between different topics and link with some crappy arrows and add later notes of notes of notes. If something is important I underline it and then move it "to a permanent storage" (a document, a post-it, whatever). And as soon as one notebook is filled up, I destroy it and start a new one.

It helps me a lot to unload things I have in mind, as if I did a kind of quick brain dump to reuse my (not so huge) brain RAM for other more relevant topics. It is like in meditation when you're told not to ignore distracting thoughts, but instead to "acknowledge them" and then go back to the meditation.

Digital notes

Since 2009, at most jobs I've also kept a "digital notes" document. Sometimes it's more of a cheatsheet of how-tos, commands and technical ceremonies you need to perform (e.g. deploying to staging requires A and B, then go to C then summon D and wait for a solar eclipse). Other times, is a collection of self-reminders, known pain-points, or mere indexes of relevant-to-me-at-least documentation. And they always contain a bit of my brain-dumps regarding some component internals or service tweaks that I considered relevant at some point... and then forgot to ever remove from the doc.

I initially just used it myself, but then the collaboration magic happened: I started sharing it with some colleagues, and they enjoyed it (and a few times, somebody suggested an improvement here and there). Then, when mentoring new hires I decided to share the doc with them, typically with a disclaimer like "it won't make much sense now, but in the future you'll probably find something inside that will help you". And they also found it useful.

From the feedback I've people seem to like it, so I keep doing these chaotic-but-somewhat-useful docs, now both for myself and for others that come after me. When I've changed jobs I ensured it had a new owner before my last day.

Existing documentation

While I don't find useful at corporate level maintaining wikis and the like, mostly because information disperses too much and gets obsolete incredibly fast, what I try to always do since some time also are two actions, no matter if the company is big or small:

Even if not required to do so, I write a small informal GDoc technical spec of any non-trivial project. While I try to keep relevant info in the ticketing system, Github issue or whenever the task at hand originates, I like to keep notes, alternatives and research outcomes, small how-tos that could come handy later when building the project's final documentation, etcetera. I usually simply have a GDrive shared folder (either the whole company, with "all tech" or simply with my manager and peers) where I put all of the tech specs and data fixtures.

I am a firmly believer that a concise but useful README.md per repository should be mandatory. I've seen and felt the pain of struggling with a simple "how the heck do I install this service?", versus a "I simply followed the readme and in 5 minutes it was all up and running", and it's quite the difference. Sometimes it's hard to strike a balance between too short and too long, but a minimal "pack" of intro + setup + running + testing is a great initial version.

Closing remark

It might look as extra work, but both when using the physical and/or the digital forms of the notebooks, I always try to add relevant information back to where it should belong. e.g. if a service's README has no testing instructions, adding some basic steps; If there's a "how to deploy your service to a specific staging instance" but the servers list is incomplete or obsolete, just updating it. It doesn't takes much time and that's the best way to help everyone.


Previous entries