Writing a Technical Book

Posted  

writing

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 a Apress which is a traditional publisher. My Quick Guide for FirefoxOS Programming got featured in the Leanpub bestseller list in the past

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

Posted  

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

Posted  

RPG

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.

Front

Front

Back

Back

Converted site from Frog to Pollen

Posted  

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

Posted  

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...

Posted  

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

Posted  

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

Posted  

tea slice of life

Interlude

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

Posted  

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.

Mentions