Writing a Technical Book



I was inspired to write this post after reading a similar post called How to Write a Technical Book by SerHack. Not because there is something wrong with their post, but because I’d like to focus a bit more on what are your options, and also show how I like to work.

During the last ten years, I have published six technical books about programming. Most of them are self-published works but I recently published Roguelike Development With JavaScript with Apress which is a traditional publisher famous for its programming books. My first popular book was Quick Guide for FirefoxOS Programming published a long time ago. I really like that it got featured in the Leanpub bestseller at the time, it made me really proud. Besides that, I’ve spent the last sixteen years working for a major publisher of Hindu Literature in English.

I love this cover...
I love this cover...

The reason behind telling you all this, is because my comprehension about book writing has changed and evolved over time, and what I think is the best way to write a book today is not necessarily the same as my own choices in the past. Basically, I don’t want you to repeat my own mistakes.

Let’s break down the publishing process into three broadly-scoped phases:

  • preparation: in which you plan and prepare your dream book. This plan will fail.
  • writing: this covers both writing and editing.
  • publishing: the hardest part actually, publishing and marketing your book.

Every book project will need to go through all of those phases, and the most important phase, the one that will actually cause your book to fail if mismanaged is the third one. People often overlook how important marketing and having a launch strategy is for a book. Pressing publish and thinking that readers will simply flock to your book is a myth. The other two steps can be fixed while you’re working on them, and even if they’re not perfect, your book might still be successful. Let’s dive a bit deeper.


The first important decision you need to make is how much involvement you want with your book project, because if you allow it, a book project will swallow all your free time from the day you start it up to the final heat death of the universe. A book might just be a hobby project, or, it might be your job.

How much time you have to spend on it dictates how long it will take to launch it. An important aspect of a book project are the tools and workflows you’re using to produce the book. There are turn-key solutions out there that require very little effort to use, opting for such tools will free up time for you to focus on the other phases such as writing itself, on the other hand, choosing more complex tools and workflows will increase the amount of control and agency you have over your project but will add friction and consume more of your time budget.

I will explore more about these workflows on the section about _writing_, but the decision on which workflow to use should come as early as possible, preferably before you start actually writing the book.

A good outline is worth gold

Your outline is the first step towards organising your mind. The most important part of an outline is not what is in it but what you leave out of it. Books, if left to their own devices, will attempt to grow to wikipedia-size amount of content. You need to constrain your project to something you can actually conclude and that still makes sense for your audience.

The way I like to do an outline is to frame the book in terms of the Hero’s Journey. Your reader is undergoing a journey in which you’re nothing but a facilitator. You’re not there to teach them, you’re there to provide the tools necessary for them to learn by themselves. As the book progresses, the reader is presented with concepts of increased complexity. Throughout the book, these concepts need to coalesce into sample projects built by the user to cement their understanding.

Initial brainstorm for my Roguelike Development book. It didn't go as planned in there...
Initial brainstorm for my Roguelike Development book. It didn’t go as planned in there...

This means that the reader is not necessarily building a single big project in the book, but several small ones. They may compose together into a larger project, but they should be discreet enough for the reader to experiment with them as they read the book and not only when they finish it. The samples are not in service of the book, the book is in service of the samples. The samples are built so the user progress in their learning journey.

By reasoning about your book in this way, you will naturally create a project in which the reader is the centre of attention. It is all about their journey. This keeps the book interesting, and avoids one of the most important pitfalls in my own experience which is writing a book that reads like a dictionary or an encyclopaedia. I find those kind of books useful as references, but they don’t usually make for a pleasant reading experience when you attempt to read them from front to back.

My outlines are chapter based. I will write the chapter tentative title and a bullet list of all that the reader should learn in that chapter. The chapters will be organised so that all the content is written to answer a need of the reader. The answer to that need might be in the form of new concepts, or new applications of a concept that was previously seen.

For many chapters in the Roguelike Development book the reader is building a dungeon-crawl game with a fixed dungeon layout. To progress in their journey to understand the basics of roguelike development, they need to learn more about dungeon generation. A whole new sample is built just to teach basic dungeon generation using BSPTrees; The chapter is written to present these concepts but it is the reader’s act of implementing the sample that actually unlocks the learning experience. The following chapter is a new application of the previous concept, the BSP-based generator is used to create multi-level dungeons. It is a journey of understanding through tinkering with code.

It is important to understand that the outline is not written in stone and that as you write your book, you’re allowed to revise it and radically change it if you realise that it doesn’t actually work.

The book ended up with 9 Chapters and 314 pages.
The book ended up with 9 Chapters and 314 pages.

Samples before writing

It is important to develop your samples alongside your outline. Unless you’re super confident in your mental abilities to hold everything in your mind as you plan your book, you will benefit from a practical hands-on approach during this phase.

If each chapter will include a sample, then build them all now as you write the outline. This will help you debug your own outline by surfacing problems with your plan early before you’ve commit too many words to the draft.

Once your outline and samples are good enough for you, it is time to move on to drafting.

Writing and Editing

People who have never written a book tend to think that writing is the hard part. It is not. It is the easy part. Creating your first draft of a technical book is easy. The hard part is editing and revising it so that your draft becomes something that is good enough to share.

If your outline has been through the initial debugging that happens by building all the samples, and everything is fine with both the plan and the samples, then writing will should feel like a natural consequence of your plan. There should be little friction as all decisions about what goes into each chapter have already been made, it just time to write the content (I know, easier said than done, but easier than many think).

This is also where you need to decide on a workflow, and just like anything in the tech world, there are too many options and it is impossible to recommend the perfect solution. These are some of the things you need to decide about:

Traditional publishing or Self-publishing

Many people think that self-publishing is the last option that an author should choose. That it only happens after they’ve been rejected by too many publishers, that they give up and self-publish. This could not be further from the truth. Many authors, me included, will consider self-publishing first and only go the traditional route if they can find a really good reason.

The discussion about this decision is too complex for me to tackle in a simple subsection, so for now let me do a simple bullet list of pros and cons for each.


  • PRO: You get more money per unit sold.
  • PRO: You have full control over editorial decision.
  • PRO: You have full control over all the process really.
  • CON: You have full control over all the process really.
  • CON: You need to do everything yourself, or hire people to do it.
  • CON: It is harder to get your book into bookshops.

Traditional publishing

  • PRO: You have a team working with you (on good publishers).
  • PRO: You have professional editors looking over your draft.
  • PRO: You don’t need to worry about the publishing part of the process.
  • CON: Publishing and marketing tend to be black boxes, you’re not privvy to the plans.
  • CON: Getting the book into bookshops still hard as most publishers are POD for books that are not from really famous authors in the tech field, you still can probably order the book from a bookshop, but they might not carry stock in the shop.

If you choose to go with traditional publishing, this is where you need to stop and start reaching out to publishers. Some cool ones in the computer programming ecosystem are The Pragmatic Programmers, No Starch, Apress, Pakt, Manning.

You should find who is the acquisition editor for the area that you want to publish in is in the publisher’s you want to work with. A good way to do it is to pick competitor books and look at their frontmatter to see who the editors were. They are usually a LinkedIn or Twitter message away from you. Reach out to them with a pitch. If they like it, they will tell you how their proposal process work. You will need to adapt your outline to whatever that publisher needs, and then follow their workflow.

Going through the self-publishing route provides you with much more option. I can’t go over all the options available much like a web developer can’t list all the possible ways to create a web app. What I can tell you is that there are some really easy ways to do it, and some others that are more involved.

Self-publishing, the easy way

In my own personal and very subjective view, the easiest way to self-publish a book is through Leanpub, which is a SaaS platform that will not only provide you with the tools and workflows to write a book, but also provide you with the means to sell it with their own store handling all the logistics and payment. Your first 100 books in Leanpub are free but after that you will need to go for one of the paid plans. Depending on your needs it might be worth going with their Pro plan which provides more features such as print-ready PDF export. I’m a Pro user and published four books with them.

Self-publishing, the new easy way

A new lets-serve-all-your-author-needs solution that is growing a lot in my heart is Reedsy. They provide a marketplace to help you meet all kinds of professionals you need—editors, copyeditors, marketeers, cover designers, beta readers, etc—but they also have a kick ass online editor for you to write your book. You can use their platform to write the book, hire the professionals listed there to work on the book, and from the same platform generate the eBooks and ready-to-print PDFs.

Also, they have a wonderful YouTube Channel and blog, with a ton of content about creative writing. Their platform is more geared towards non-technical books, but can still be used to create them.

To be honest, I haven’t covered half of all they offer. Just check their page. They’re awesome.

Self-publishing, the desktop apps way

Do you prefer to work with desktop apps? Me too. So, the darling of the industry is an app called Scrivener. It is worth every penny. If you’re not going to remember anything from this (very extensive) blog post, remember this: Scrivener is worth gold.

I can’t stress how good Scrivener is for your writing career. It is worth buying a license, and devoting time to master it. You will be able to use it throughout the years and it will become your faithful squire, always ready to lay a helping hand in your journey.

I'm writing a RPG book with Scrivener.
I’m writing a RPG book with Scrivener.

You can use it to manage your outline, your research, write your draft, do all the revisions, and then generate eBooks and pdfs.

If you want even prettier eBooks, then combine Scrivener with another app called Vellum, and you’re good to go. Vellum is mac-only though.

My latest book: Development Oriented Development was planned, organised, written, and assembled with Scrivener.

Cover for Development Oriented Development eBook
Cover for Development Oriented Development eBook

Self-publishing, the FOSS way

Yeah, I bet the FOSS readers among you were already getting nervous with all the proprietary software listed above, right? Well, there are many FOSS options. You can go with novelWriter which is a tool that I’ve discovered recently, and haven’t yet used, but that seems quite promising.

It reminds me of Scrivener, but with the advantage of markdown, I’m keen to try it out some day. Unfortunately, it doesn’t appear to generate proper eBooks.

The swiss-army knife of book publishing in the FOSS world is Pandoc, which is actually used behind the scene by many desktop apps and SaaS. It is an extremelly flexible and powerful tool. Mastering it will take a while and might be beyond what you’re willing to do, but it is worth it.

Another important app is Scribus which is actually a Desktop Publishing app like Adobe InDesign and Affinity Publisher. You can use it to layout a book that you’ve written elsewhere, but it has a steep learning curve compared to all the softwares listed in this article.

Drafting and Editing

Once you have decided on the tool you’re using, it is time to draft. Your manuscript is the content of your book before it goes through layout and typesetting. You will evolve the manuscript by creating multiple revisions of it. Your first draft will go to an editor, who will return it to you after their initial pass is done. You will repeat this ping pong with editors, copyeditors, technical reviewers, and artists, until all the stakeholders are happy enough.

The first draft sometimes resembles the final book very little, in other times the editor is basically fixing just some little grammar mistakes. This depends not only on your draft, but also on your editor. Some publishers might be understaffed and their editors don’t have enough time to invest in your project, you might be self-publishing and paid just for simple copy editing instead of developmental editing.

It is important to realise that this initial draft is not your final product. It needs to go through revision, and that the revision objectives are beyond just fixing grammar and typos. You might need to refactor much more. That is when alpha readers become very valuable. Give the book to trusted readers and let them help you figure out what needs changing. If you’re into FOSS, develop the book in the open and let contributors help you all the way.

By the end of this process, you should have eBooks and maybe ready-to-print PDFs.

Publishing and Marketing

Oh boy, I’m shooting myself on the foot here. It is impossible to cover all that one needs to know in just a section of a blog post. Let me first plug an online course: The Self-Publishing formula. They have many courses, a podcast, and a community that covers all you might need to know to make your book a success after you have actually written the book. It is not cheap, but it will cover so much content. It will teach you so much stuff. If you counted the hours you’d spend to research and learn all that on your own, you’d end up spend more time and money than actually paying for the course. I’m a happy student there. Be aware that the course is focused on fiction and not technical publishing, but that the methods and tools presented there work just as well for tech books.

It is important to have a marketing plan. Hitting publish is no guarantee of success. Readers won’t magically appear unless you have a large following already. Heck, maybe you’re Evan You writing a book about Vue.js, when you hit publish, readers will definitely flock to your book. Heck, I’d buy your book. But for most authors, having a marketing plan is a must.

Some things that will really help your book:

  • Be active in the communities around your book’s main topic. Active doesn’t mean keep plugging your book, it means be a good citizen in that community and help others without constant upselling.
  • Depending on your niche, you will need to pay ads. I don’t have any experience with them, but that course mentioned above does.
  • Make it easy for readers to engage with you. Their success will bring a smile to your face.
  • If being an author is part of your life, and you can see yourself publishing many more books. Create a mailing list to keep track of your writing. Encourage your readers to sign up with reader magnets.

You need to actively promote your books even if you’re not self-publishing. Traditional publishers will put too many books out every year and they will put marketing effort on the big sellers only. You need to help sell your books, no one will do it for you (unless you hire someone to do it of course, go see Reedsy).

Anyway, this has been a gigantic blog post. Kinda of a brain dump. If you want to know more about any aspect of what was written here, feel more than encouraged to reach me over Twitter, Mastodon, or WebMentions. The contacts are below this post.

TroikaFest! Report 1: Working on 'Three Days in Theme Park Red'.


RPG TroikaFest Troika

TroikaFest! is in full swing and when I looked earlier today there were already more than 30 submissions on itch.io. I’ve been working slowly on my little sphere nee adventure for the jam since the first and hope to be able to ship some alpha version soon.

I was supposed to be working on another adventure for Troika! called Hyper-Acryllic Railroad but then on the late hours of the 31st of March, I had a totally new idea that was much simpler to move forward. In the beginning it didn’t had any name attached to it, but it happened in a sphere that was a theme park. As the ideas bubbled in my mind, the name became obvious: Three Days in Theme Park Red.

My own home has been too distracting for me. My wife and I have been working from home for the past six months, and personally, I’ve been working from home for about 16 years. So, staying in the computer at home felt too much like working. I was sure that to fully develop this seed of an adventure, I needed to be outside, away from my own work environment. Lucky for me, it was a sunny day. I took my paper scratchbook, a gazillion pens, and went for a walk.

The initial brainstorm for Three Days in Theme Park Red.
The initial brainstorm for Three Days in Theme Park Red.

Once the sun was going down and London became a bit too chilly to be writting gonzo stuff outside, I moved back home and spent some hours transferring what I had into a scrivener project.

Scrivener is awesome.
Scrivener is awesome.

I wish I was working faster, and that I had something more useful to share already. Maybe later this week, I’ll be able to share some alpha version of this adventure.

Backwards Fighting Fantasy



Just released my entry for pleasurecardrpg jam.

Make an RPG-related thing that fits on a so-called business card. You are strongly encouraged to get it printed. Because printing stuff is fun. Adventures, games, expansions, hacks, whatever the heck you think is appropriate.

I made a micro-rpg called Backwards Fighting Fantasy. I can actually attach it here as a blob.





Converted site from Frog to Pollen


slice of life

Just spent about twenty days converting this site from Frog to Pollen. It behaves more or less the same as before but some of the previous features are gone. So far I am happy by the flexibility that Pollen will unlock for me in the future.

The one thing that is bugging me is that I don’t have tag pages anymore. Everything is now bundled in the topics page. I don’t like it but I don’t have the willpower to implement individual tag pages right now.

Well, as I wrote this I just noticed a major bug. The topics are case sensitive... everyday is a day for bug hunting.

Lua, a misunderstood language


programming lua

Lua is one of my favourite programming languages. I’ve used it to build a CMS for my old educational website, for creating cool IoT hardware projects, for building little games, and experimenting with network decentralisation. Still, I don’t consider myself an expert on it at all, I am at most a somewhat competent user. This is to say that I have had exposure to it in various contexts and through many years but I am not deep into its implementation or ecosystem. Because of that, it kinda pains me when I read blog posts and articles about Lua that appear to completely miss the objective and context of the language. Usually these posts read like a rant or a list of demands. Most recently, I saw a post about Lua’s Lack of Batteries on LWN and a discussion about that post on Hacker News that made me want to write back. In this post I’ll address some of the comments I’ve seen on that original article and on Hacker News.

Lua should be considered a toolkit

I think it was Hisham who in his talk in LuaConf 2017 said that Lua is minimalistic (aka: “there are zero ways to do it”). This was of course about Lua offering mechanisms over policies, or how it unlocks agency in the developer by letting them adapt the language to suit their environment and not vice versa. Lua should be viewed as a base ingredient to which you add whatever you want. If you are making fruit smoothies, Lua is the milk and you add whatever fruits you need.

People who want batteries want a ready-made powertool full of opinions. They are not looking towards Lua in the context that Lua wants to exist. It is like looking at a boat and complaining it can’t fly. It was not meant to fly. Unless you build the rest of the place and make an hydroplane out of it. It is up to you, Lua doesn’t care.

Lua has always been a language for scripting applications. It has always been assumed that you’d build your domain specific code using something else and embed a Lua engine in it to make it flexible. Are you building games? You build your whole engine in whichever language makes sense for you game, including the domain specific stuff that only your game cares about, and then add Lua to it so that you can script and tweak your game without recompiling the source.

The same context applies to other software that offers Lua as the scripting language for their plugins or add-ons, this is what Lua has been built for, it offers advantages to this approach. The fact that you can write the whole software in Lua is a side-effect of it being a good language but it was not the primary use-case for it.

People who wants battery-included Lua do not realise that there are plenty of battery-included Lua distributions floating in the wild. Other developers picked Lua, added what they thought was a good baseline, and are shipping a complete package. You too can build your own battery-included Lua that has the stuff you want. We don’t need blessing from the Lua team at PUC to do it. This is how it is supposed to work. You pick the language and assemble what you need.

This leads to robust software since the developer are responsible for making the calls. You are in complete control and can make the decisions that are suitable for your development. There is no situation where Lua team, or LuaRocks team, can prevent you from doing what you want like the drama that has been happening inside the Elm community. You can grab the source for the version you want, and then never again look at Lua community.

I think that you can only appreciate Lua when you embed it on your own software. Until what you are building is a combination of some code in other language (such as C) and Lua, the power of Lua will not click for you. Not only the power, but the way of Lua will not click for you. If all you’re using is 100% Lua source code, it will feel just like another scripting language–not unlike Python, or Ruby–and you will start trying to analyse Lua in terms of those other languages, which are not really comparable since they have different objectives.

Complaints about 1-based indexing for arrays

Mentioned in this comment. I often see this kind of complain from people who think that the C way of doing things is the only valid way. It would be great if people spent more time thinking about why use a 0-based index instead. C uses such indexes because the value is actually a multiplier that you can use to find the memory offset for the location of the data. If you have an array, and thus a pointer to the starting position for that data in memory, and you know the size of the array elements, you can multiply the size by the index, sum with the pointer value, and get the data that corresponds to the element referenced by that index. That is it. Indexes are zero based to help you find stuff in memory when you have a pointer which is basically all that C gives you.

Using 1 as the initial position for an array makes sense when you’re talking like a human. When you and your friends are in a queue waiting for your hotdogs, you might say to them that you are first in line. I doubt you’ll say you are zeroth in line. We usually start to count from one. When a baby completes its first roundtrip around the Sun, they’re one year old, not zero years old. Also, 1-based indexing help when you are doing iterators, you don’t need those hacks such as i-1 or counting til i<total. You can count from 1 to the total and be fine, like a normal human would do. If I remember correctly, this was a Pascal convention. Pascal is a language that deserves a ton of love IMHO.

Complaints about object-orientation

Lua is not object-oriented. That is it. Lua has tables which are a very flexible data structure. Lua has Meta Tables, which enables even more flexibility when using Tables. This should be approached as a toolkit (can you see a theme here?). Using Tables and Meta Tables, you can build a ton of cool stuff such as namespaces, and fancy OOP systems. You are in control. Do you want to build a system like NewtonScript with its dual parent prototypical inheritance? Well, code it away. Lua offers mechanisms, not policies. You use these mechanisms to build what suits you. You’re not tied to what PUC or a library author offers you.

Some language will replace Lua

Mentioned in this comment. Be aware that I am not singling Janet here, I really like Janet. Many people don’t realise that Lua is extremely nimble. Lua can be built by compilers using the c89 standard (even though the default is c99 IIRC), using very little assumptions about the hardware it is running on. This makes it a prime candidate for embedded work both in hardware and inside your own apps. Many languages that are touted as Lua replacements require more resources and make more assumptions about the hardware and operating systems they are running on. Janet is still awesome (and it builds with c89 IIRC) though.

Lua is quite small, and I am not saying about binary size and resource usage. I am talking about source-code complexity. Lua is small enough that newbie developers can understand its internals well and keep it in their mind. This makes it a great language for academic research. A language that you can comprehend easily will foster experimentation. Lua is specially well positioned to be used for both research and practical purposes.

Final words

Originally I titled this section Conclusion but that felt wrong. It is a post about Lua, so instead of giving you a conclusion, I will give you final words–just another piece in your toolkit–so that you can form your own conclusion.

I am not a computer scientist. I was a student at PUC-Rio from 1998 to 2001, and while there I never met the Lua team even though I used old CGILua for work at the time. I quit engineering and graduated from another university as a filmmaker and scriptwriter. I don’t have all the academic background many people reading this post have, and yet that never prevented me from using or enjoying Lua. I was a speaker at LuaConf 2017 and presented an Internet-Connected Automated Drink Mixer I built. I chose Lua for that machine because it felt right. What I wanted was not a language full of batteries and opinions. I wanted another tool in my toolkit, something that offered me just enough mechanisms to allow me to build what I wanted.

When you approach Lua, don’t look at it like a product. Approach it like you approach a LEGO set. Lua offers you bricks, you provide the imagination, design, and in the end, you build the product.

Oh, and this is the video for my drink mixing machine…

So, I almost died making tea today...


Slice Of Life

It begun when sat down to write a book. As I outlined what needed to be written, I decided to make tea using the infuser I got for Christmas. I was one of those glass tumblers you probably saw on ads on Instagram. It looks like this:

Separation of Tea my ass, it almost separated my life from my body

Separation of Tea my ass, it almost separated my life from my body

You basically add tea leaves on one chamber, hot water on the other, and flip for them to mix. We noticed a quirk that I should have paid more attention in hindsight: unless we inclined the bottle a bit to prevent liquid from being in contact with the whole surface area of the filter between chambers, there would be no air exchange between them and the water wouldn’t flow. The mathematically inclined among you already knows that this means that the infuser is kinda hermetically sealed, and you don’t want pressure building up on fragile glassware without pressure gaskets. Of course, I thinking that now after I survived the fucking bottle explosion, at the time I was happy making white tea with cocounut and wondering about my outline.

I inclined the infuser away from my body, at about a 60 degrees angle. This story would be very different had I inclined it towards me instead. It went of just like a fireworks shot. The bottom third of the infuser–which was up and oriented away from me–exploded throwing shards of glass and glass powder on the three walls of my kitchen, the living room, and the corridor. It took me a couple seconds to understand what had happened, and then to realize it didn’t hit any part of me.

how it looks now

how it looks now

There were shards every where…

glass shards everywhere

glass shards everywhere

glass shards everywhere

glass shards everywhere

glass shards everywhere

glass shards everywhere

I’m still shaking a bit, I even found glass on my feet. I was wearing socks, it passed through it but didn’t hurt me. I probably stepped on it. My wife and I just spent the best part of an hour cleaning things up. I am sure there is still pieces of it somewhere in the kitchen.

Winter Book Haul


slice of life

A good way to start the day: coffee, cake, and books.

A good way to start the day: coffee, cake, and books.

Yesterday, I walked 12km all the way to Foyles and back to buy some book. There are some more direct routes but I enjoy losing myself in the streets of #london and discovering cool new places. For example, I found a little coffee cart that sells espressos using lever machines. They were closing by the time I walked by, but now that I know they’re there, I can go another day and try it out.

In that book haul, I finally got my hands into The Name Of The Wind, by Patrick Rothfuss which many reviewers I follow claim is an absolute gem, not only because the usual reasons but because the author’s prose is a masterpiece. I’m really looking forward to reading it. If you’ve never heard of it, well, just check these quotes about it from other authors I really admire:

“The best epic fantasy I read last year…. He’s bloody good, this Rothfuss guy.” — George R. R. Martin, New York Times-bestselling author of A Song of Ice and Fire

“Rothfuss has real talent, and his tale of Kvothe is deep and intricate and wondrous.” — Terry Brooks, New York Times-bestselling author of Shannara

It is a rare and great pleasure to find a fantasist writing…with true music in the words. — Ursula K. Le Guin, award-winning author of Earthsea

The characters are real and the magic is true.” — Robin Hobb, New York Times-bestselling author of Assassin’s Apprentice

Masterful…. There is a beauty to Pat’s writing that defies description. — Brandon Sanderson, New York Times-bestselling author of Mistborn

Continuing with the fiction books in the haul, I also got Ink & Sigil, by Kevin Hearne. I’ve been intrigued by this book since the very first moment I read about it in a tweet. It is an urban fantasy set in Scotland and it contains curses, craft cocktails, and fae. I’m a sucker for Fae. Apparently, this book is set in the same universe as his other books, which I haven’t read, but they’re not pre-requisites for enjoying this one.

The other books are about creative writing and part of my study of the field so that I can better prepare myself for a career transition into fiction writing. Bird by Bird, by Anne Lamott is a memoir about writing. Many people says it contains really good insight and advise. I decided to buy it after reading this quote from it:

“Thirty years ago my older brother, who was ten years old at the time, was trying to get a report on birds written that he’d had three months to write. It was due the next day. We were out at our family cabin in Bolinas, and he was at the kitchen table close to tears, surrounded by binder paper and pencils and unopened books on birds, immobilized by the hugeness of the task ahead. Then my father sat down beside him, put his arm around my brother’s shoulder, and said. ‘Bird by bird, buddy. Just take it bird by bird.’”

The last book in the haul, and the largest one in the haul is Howdunit, by members of The Detection Club. Even though I’m more of a Science Fiction and Fantasy reader, I’ve always enjoyed whodunits and detective stories. In the series I’m planning, I’m going to merge these two genres by having a detective in a fantasy setting. I know this is not original and has been done before but, most stories have been done before and we still read them anyway. This book is a collection of articles by various members of The Detection Club, the oldest crime writing network, and I’ve heard mixed things about it. I bought it because I suspect that there are hidden gems in it. Oh, that club has existed since 1930, they have a silly oath:

Do you promise that your detectives shall well and truly detect the crimes presented to them using those wits which it may please you to bestow upon them and not placing reliance on nor making use of Divine Revelation, Feminine Intuition, Mumbo Jumbo, Jiggery-Pokery, Coincidence, or Act of God?

This is a part of their fairness rule which meant that both the detective and the reader should have a fair chance of guessing who the villain is based on the clues before the eventual revelation. I kinda like this because I’ve read my fair share of books in which the solution is completely out of the blue, or as we say in Portuguese: a porra do autor tirou essa merda do cu. I like the idea that the reader is in the same quest as the character and that the revelation makes sense and can be infered by people who are paying enough attention.

Discovering Gong Fu Tea


tea slice of life


When my parents came back to Brazil after vacationing in China for a month, they gave me a Gaiwan and some tea. I didn’t really know how to use it, or how to properly brew the teas they gave me. At the time, I thought I didn’t like those teas. I was brewing like the I was taught to, in a teapot with long brewing time, and then serving on the gaiwan (which I mistook for a tea cup).

Now, many years later, I understood how it was supposed to work. And it is delicious.

I’m fond of little rituals. I enjoy drinking coffee as much as I enjoy preparing it. Lately, I’ve come to think that I have been drinking too much coffee and that maybe I should add more tea in my life. What I want is not to replace coffee with tea but to balance between them. I used to be a tea person before I became a coffee person, so it is a bit like going home.

Upon researching more about tea, I decided that eastern (specially Chinese) style of tea is more suitable for my tastes than western (aka English) style of brewing. I took a deep dive into the Mei Leaf YouTube Channel — which is a tea bar and shop with an awesome tea facts and skill channel — and learned a ton of stuff.

“The greatest realization I had was how wrong I was with my past experiences with a gaiwan and oolong teas. I was doing it all wrong.” — WrongDog, the tea-waster

After watching a ton of videos in that channel, I noticed that their shop is actually at a 25 minutes walk from my flat. OMG! It was destiny! The heavens want me to drink tea! So even though it was 2°C, I wrapped myself in many layers of excitement and walked to their shop.

The shop was full of people (thankfully it was a very large shop and everyone was wearing masks. Also full means about six people, covid changes perspectives). I waited until they were all served and was then greeted by a very helpful human who helped me buying a Gong Fu Tea Solo Kit and many sample packs.

If I enjoy the experience and little rituals involving tea, I plan to slowly upgrade to fancier sets as my taste improves.

Gong Fu Tea Solo Kit

The Kit comes in a fancy box.

Gong Fu Solo Box

Gong Fu Solo Box

Even its interior is fancy and well made.

Gong Fu Solo Box Interior

Gong Fu Solo Box Interior

I can see this box having use for many many years. Inside it there was a 70ml gaiwan, a cup, and a towel.

gaiwan, cup, and towel

gaiwan, cup, and towel

I also got seven tea samples.

seven tea samples for the Dwarf-lords in their halls of stone...

seven tea samples for the Dwarf-lords in their halls of stone…

I’m in love with all of this already. Time to make some tea.

I had no idea what to start with, so I went with something I tasted before: green tea. Their green tea looks really nice:

Imperial Green Tea

Imperial Green Tea

This is imperial green tea pre-Qin Ming, which means it was harvested before the spring IIRC. To be honest, I’m not that fond of green tea but among the various green teas I’ve tasted in my life, this was probably the best.

Gaiwan and green tea

Gaiwan and green tea

I’m still learning to control the gaiwan, so some leaves escaped into the cup (and that is fine).

Can’t wait to try the other flavours.

Considering moving back to the Mac


slice of life

I have been a vocal supporter of the Microsoft Surface line for some years now. You may have seen my post about the joys of the Surface Go or been one of those viral readers that almost took my server down when I posted my impressions of the Surface Pro X. Since 2015 I had the Surface 3, Surface 4 Pro, Surface Go, and Surface Pro X, and loved all of those machines, yes even the Surface 3.

These last five years have with Windows 10 have been a wild ride. I was not familiar with previous Windows versions. I used Windows 95 for a while, but as a Kid, I didn’t dabble much in it. I got my first Macintosh—an iBook G3 indigo blue—in 1999 or 2000; I don’t recall the exact year but, from that day till 2015, I was an Apple user. Even after getting my Surface 3, I was still using the Mac as primary. The Surface was for fun and comics. I only started to use Windows 10 as my primary device when I got the Surface 4 Pro. So even though many recent developer friends know me as that guy using a Surface, I was that guy using an Apple for a much longer period. I used to develop desktop apps for MacOS 9 and run betas of MacOS X before release. Macs are very familiar to me, have always been.

Still, I really enjoy my Surface devices. What I love about them is not the software, it is the hardware. I’m in love with the form-factor. I still glee when I switch from laptop to tablet, from keyboard input to pen. Windows 10 is good enough, doesn’t annoy me much, doesn’t prevent me from enjoying the ultra mobile experience the Surface line provides.

The fun ride starts its descent into the realm of frustration with the Surface Pro X. I got it before the pandemic and I paid for all the upgrades I could. It has a ton of space, 4G, and a pretty decent battery-life. I live in London and my plan was to use it to work from parks and coffee shops without the need to worry about Wi-Fi or power sockets. It delivered marvelously on this promise; it was an exceptional experience.

The experience degrades when you approach it as a developer. If you’re a Web Developer, that machine has you covered. With the WSL2—Windows Subsystem for Linux—you have AARCH64 Ubuntu just a click away. Unite that with the remote connection from VSCode (connecting from Windows 10 to the WSL) and it becomes a productivity powerhouse. If you’re a Web Developer, it is a damn great machine.

The problem begins when you’re like me and love desktop apps. Don’t get me wrong, I work as a Web Developer, I love the Web. I just don’t think that everything needs to be Software as a Service or an Electron Application. Wanting local desktop apps in a machine with a snapdragon-based CPU and 4G always-on connection might sound wrong, but desktop apps are usually quite lightweight and require fewer resources than running something over the internet. More than using desktop apps, I enjoy creating them. I’m tired of being a Web Developer, I’m frustrated with the modern Web Development stack. I miss the experiences I had 20 years ago where you could assemble a good-looking app without being a designer just by using a nicely packaged development experience like XCode/Cocoa. I miss well designed, comprehensive GUI frameworks.

Some of you might think that running VS2019 and doing dotnet apps would be the way to go for me, and let me be honest, I thought so too. I watched Microsoft Build keynotes and talks. I got excited about tech and impressed by the new WinUI stuff. But that doesn’t work on the Surface Pro X. The desktop apps part of the development experience is all missing. There is no native support for winforms, wpf, WinUI. Visual Studio doesn’t see the local machine as a viable target at all. When I asked how to develop desktop apps for ARM64 on a Microsoft Forum, the answer was to use two machines, one x86–64 machine to develop and the ARM64 machine for remote debugging, and that the only available paradigm was UWP. Microsoft has a lot of qualities, I’m specially impressed with how it keeps retrocompatibility with itself but, having so many toolkits and options might frustrate to a new developer because there are no guidelines on their docs on how to use a Surface Pro X to create desktop apps. It is a 15gigs machine with a kick-ass CPU running a full Windows 10 experience, I should be able to use it for development but I can’t.

It has been more than a year since the Surface Pro X launch, there is even a new version out there, and there is no native support for being a desktop application developer. There is no x64 emulation. You can’t port apps to it because of the missing GUI stuff. You can’t develop apps for it from it because VS2019 is stupid. You can’t run the apps you need because they don’t offer x86–32 versions anymore and don’t offer native ARM64 versions either. I’m tired of waiting for Microsoft to get its act together and make this platform be all it can be.

The last nail in this coffin has been the release of M1-based Macs. Apple is an expert in doing these ISA transitions. I was a Mac user during the PowerPC to Intel transition, and it was mostly fine. This time it appears the experience is even better. From day one they have all the development experience working and have x64 translation so you can run your favourite apps. It is no secret that I want to work more with content than with development. I see myself as a storyteller; I enjoy writing and doing videos. I am also a developer, but that is just so I have delightful stories to tell and can pay the bills. My content creation apps are not available for the Surface Pro X, but all of them run on the new M1 Macs, some are even native. The few apps I have to support my writing on the Surface Pro X are running under emulation, no one bothered porting to Windows on ARM. There is no good video editor for the Surface Pro X, you can’t use it for video production at all, which is why there are no new videos in my YouTube channel (rendering video on my Surface Go takes all day).

I have a simple entry-level MacBook from 2019 here. This week I upgraded it to Big Sur and was positively surprised after the catastrophe that was macOS Craptalina. Yesterday evening I launched XCode and did the official SwiftUI tutorial from Apple. Bear in mind that the last time I used XCode it was the early days of MacOS X and I was programming in Objective-C. I don’t know Swift, nor have I been exposed to any mac GUI stuff after nibfiles. In couple hours I had a nice looking iOS application. The experience was good and Swift is not too bad. I wonder if SwiftUI can be used to ship desktop apps…

I really enjoy developing for the Mac, always did. In my 20s, with barely any knowledge of programming, I could create ugly-but-functional apps like this early alpha below (that was my very first Objective-C/Cocoa application):

An early alpha of BlogWorkz for MacOS X, look at all that brushed metal

An early alpha of BlogWorkz for MacOS X, look at all that brushed metal

In those days, I moved away from Objective-C/Cocoa because the market for such freelance development didn’t exist in Brazil. I ended up using cross-platform toolkits and languages so that I could develop on a Mac and deploy to Windows or Linux. I wonder what my life would have looked like if I kept doing native development. These days Macs are much more popular than twenty years ago, I can see a potential market for passive income from small desktop apps. Something to build on my own time while I work on my books and videos.

Things the new M1-based MacBooks would allow me to do that I currently can’t:

  • Run Blackmagic Design software such as DaVinci Resolve and the ATEM control software;
  • Create simple desktop apps for my own amusement and maybe some passive income;
  • Run the most recent versions of Scrivener and other applications focused on writers;

I’m tired of holding the Surface Pro X and watching its untapped potential. It is a wonderful machine, but Microsoft is placing all its effort into Web and Azure stuff. Desktop apps appear to be a forgotten land on that platform, an afterthought. I’d love to be able to use it for all my needs because that is an exciting machine but, a boring old laptop form-factor is the way forward for me. I need to use a machine that permits me to be who I want to be and not tie myself to something exciting, but that is holding me back.