Getting Started with Writing a Technical ebook

The early release of my ebook Juggling JSON with jq comes out tomorrow! However this post is more about the process of writing the book itself.

Getting started on an technical ebook, (such as Juggling JSON with jq), requires a bit of upfront setup. On the ebook side, I decided to go the route of writing the book in Markdown, and generating the various formats using Sphinx. While I feel most comfortable using Markdown, and yet Sphinx uses reStructedText by default. So I had to coax Sphinx to accept Markdown by using a project called m2r. Generating the PDF version of the ebook took a bit to get working. Sphinx uses LaTeX to generate PDFs, and LaTeX while powerful can be clunky to work with. I wrapped everything up with an invoke script, and now I can quickly generating new versions of ebook in the various formats I want to support.

Something unique to writing technical books, is the need to have actual working examples. You can learn by reading, but working through exercises and examples re-enforces that learning. In the case of Unjumbling JSON with jq, I needed an example REST API that readers play with. I searched for some nice open APIs, but nothing seemed very compelling. Many of the open APIs require some form of user registration and non-trivial authentication method that would complicate the examples in the book. So I setup a simple demo API for the book. Thankfully with Docker and Flask, that isn’t a particularly daunting task. (Dockerizing most of my webapps definitely made my live easier overall.)

Finally using Gumroad made marketing and selling the book a lot more approachable. Getting everything setup for e-commerce is a daunting job, if you plan on doing it yourself. Thankfully for ebooks, and similar digital products, Gumroad solves most of the problems one can encounter. I definitely recommend using them if you are planning to do something similar.

Book Announcement: Unjumbling JSON with jq

jq is an amazing tool for querying and manipulating JSON in command-line, that I learned about from one of my good colleagues, Eric Olsen. And I feel that jq deserves a good book describing how to use this tool. Hence I am writing a book called Unjumbling JSON with jq on the topic.

As mentioned in a previous post, I originally planned on writing a single book on both jq and httpie. I divided the original book in two, because there is only a small overlap between the two. I wanted to show examples of grabbing a REST API response via httpie, and parsing the JSON output with jq. However basic querying a REST API is something that could be covered in a short section. By writing the books separately, I will be able to release them faster, and the books will be much more focused.

I plan on selling early drafts of the ebook on August 10th. Buyers of the ebook will get regular versions of the evolving drafts of the ebook, and a free upgrade to the final version of the book. I want to release the early drafts to get early reader feedback. In addition readers of the book will have access to the REST API that accompanies the book.

You can order the early version of Unjumbling JSON with jq from here].

Just to Write

I feel as if this blog were a summer residence of sorts.  I do not live on it.  I do visit often or as often as I’d like to.  And when I do I first must dust the cobwebs, and vacuum the dust before I can do what I really want to.  What I really want to do is write.  Write and write with near abandon.  Just the shear joy of writing makes if worthwhile to write.  Just like this post.  This post is a creation of spontaneity and a love of the art.  Nothing more.  Nothing less.

Unfortunately, today like many days are filled with non-writing tasks.  Clearing the decks, organizing the mess of everyday, healing myself of this *ahem* nasty cold.  But how I yearn to write just like in the old days.  A keyboard on a strong wooden table, in sunlight or the light of a desktop lamp.  I know… what can I say… I am if not a romantic.

That is all.  I just wanted to share this with my readers.  That and the realization that I should spend less time dealing with the chores I am not interested with.  And spend more time doing things more beneficial to all.

I am also lucky to have met someone, who has helping me challenge my thoughts of what I do.  And to pursue the passions that I have.  I think I shall have to do just that.  One of those things is write more and worry less.  You can’t please everyone with your writing.  And you never will.  The moral of the story is to write about things important to you.  Enjoy the journey and do not worry if you please others.  I shall have to do just that.

Ash Wednesday

Today is Ash Wednesday.  What a day it was.  Started off with a dentist, ended up with me walking through slush in the driving wet snow.  Not exactly the funnest of days.  But I guess appropriate for the beginning of Lent.

I’ve decided that this Lent, I will work on resolving a nagging deep personal issue.  I will not go into the details, but it is a serious issue that needs resolving.  Along the way, I also want to dedicate more of my time and works to the Lord.  After He gave me all my gifts, my life and everything.  It is only fair I do something in return.

I plan on doing a lot of writing and editing of writing, inspired by Catholic faith.  I think this will not only be a good direction for my spiritual development, but also my personal too.  Considering that I am an editor of the Alexandrian and a writer it just makes sense.  And also the amazing comments from my readers… I feel like I should do this:

So my plan is to spend my free time each day writing a part of my novel, or working on the next issue of the Alexandrian, or working on expanding the magazine.  Hopefully by Easter, I will have a quite collection of work that I can offer up.  And for the benefit of my readers and friends.

Catholic Writing Reprint: Learning to Love God

Author’s note:  This short story is reprinted from the Fall 2010 edition of The Alexandrian.  It concerns about an epiphany I’ve personally experienced and that has deepened my faith.  The original publication can be found here: http://thealexandrian.org/journal/learning-to-love-god

Learning to Love God

Dorian Pula

I decided to take a short break from cleaning in the kitchen. I dried the plate in my hands, put it away on the shelf and hung the moist dish cloth over my shoulder. I wandered out of the kitchen and into the living room. The hardwood floor heated by the summer sunlight warmed my bare feet. The floor creaked every few steps I took.

The house stood empty, still and silent. The ticking of the wall clock filled the living room. I stopped a metre or so from the grey piano in the living room. A flimsy picture rested against the piano’s music stand. The picture portrayed Christ as a king wearing a regal cloak and crown of red and gold against a background of golden rays. I stared at the picture and wondered how different artists portrayed Jesus in different ways. Sometimes He looked welcoming and friendly, sometimes powerful and regal, and sometimes hurt and bloodied.

In my own mind I portrayed God as a loving but stern Creator. I envisioned Him sitting on some throne in the heavens, great white beard flowing and commanding the universe with a stern look and pointed finger. I thought how foolish it would be for His creation to go against His commandments. How foolish it would be to upset someone who could make you unexist as easily He made you exist. Not that this thought ever stopped me from doing foolish things against His will.

Still I tried to follow the two most important commandments that Jesus taught. I understood the love thy neighbour part. I learned to accept, respect and even love others. One can learn to love humanity even with its flawed attempts at happiness, love and peace. But how does one love God? After all I always envisioned God the Father, sitting from a far, looking fatherly but more or less abstracted from the day-to-day affairs of the world.

As I stood there and stared at the picture I wondered if I could ask God that question. I did not expect any real answers. After all in my mind God, not only felt distant but that also He had better things to do than to answer my idle questions. But decided to try anyways. And so I prayed for wisdom.

The air became unbearably hot, dry and dusty. The walls closed in forming a narrow street in ancient Palestine. An angry mob surrounded me wearing cloaks, tunics and sandals. The mob jeered at a convicted man half-escorted, half-manhandled by rough Roman legionnaires. I felt safe as my cloak hid my identity and let me merge in with the crowed.

I watched silently as the convicted man limped down the street toward to his execution. His figure bent under the heavy wood beam fastened to his arms. His torn and blood splattered clothes hung loosely over his torn, disfigured, swollen and bruised body. One of the soldiers pushed the man forward, causing him to fall on his knee in front of me. I recognized the man as the Lord when turned His face towards me. The black crown of thorns cut into the Lord’s swollen forehead and dark blood dripped down the creases of His face. As He laboured to stand up, I imagined my own body turning into the symphony of pain and torment that He endured. I recoiled at the sight of the gruesome, blood stained and tortured Lord. Horror filled me as I realized that some His wounds were in fact my own sins.

I looked at the Lord with pleading eyes. Why did you choose this? Why does the King of the Universe who defined the very laws of existence choose this fate? Why take this pain, cruelty and humbling from a wretched race who rejects You time and time again? Why this? There must best be some other way.

Because I love you, I respect you and honour your will even when you reject Mine. The Lord responded with a serene look that was out of place.

This is madness! Only a madman would do this. I shouted at the Lord in my mind.

Or a man madly in love. The Lord replied and first century Jerusalem melted back into the comfort of 21st century Toronto.

The house stood empty, still and silent. The ticking of the wall clock filled the living room. A hot burning tear streamed down my cheek. The comforting aura of technology and human ingenuity gently prodded me back into reality. I continued to stare at the picture. But I felt different. My heart overflowed with warmth, joy and gratitude. I wiped another tear that started growing in my eyes. Now I understood that God wasn’t some remote deity who merely watched His creation from afar. Instead God is so madly in love with His creation, He let His creation kill His only Son. And by His death and resurrection He redeemed and saved His creation, unworthy as we all are of this mad love.


There is Writing… And There is Writing

I enjoy writing, I really do.  If I did not I would not spend my time blogging and writing novels. Heck I even like writing documentation in my code at work. The written word is nothing I fear nor loathe. However there is some writing I could do without. Or rather, prefer not to do.

One such type of writing is writing e-mails to clients or business correspondence. Not that I can not communicate effectively. Rather I dislike the whole political tip-toeing on does. Formalness and diplomatic speak is something I do out of necessity.

Another type of writing I never cared about is essay writing. Yes, yes I can give argue a point and give evidence. But in high school, teachers want you to use their silly hamburger paragraphs and their thesis and conclusion setup. I mean for real? Read a real essay and see how real writers argue their points. You argue the point quickly to the point, without going on and on and on about boring redundant evidence. Just to make a point. Not to mention page length expectations. Make your point and use as much or as little as you need. Do you wonder why journalism instructors have to first unteach all the folly of high school.

So why the rant? I had to do both recently. But helping my brother work on his essays, just brings back less than fond memories of high school English. I liked the reading, but the only English class I enoyed was the one with the cute attractive teacher. I don’t blame her, because she had to teach a curriculum set out by a merry band of bureaucrats. And most of the class was not imaginative enough to write anything half decent. But irritated me to no end.

Fortunately most of my writing nowadays consists of technical work, blogging and novel writing. So once I finish helping my brother I can get back to writing my novel.

Odds and Ends and Everything in Between

When one ought to go sleep, but instead insists on staying up to finish one more thing… than one is an workaholic.  But who am I kidding here?  My excuse is really that I’ve realized that this week is a crucial crunch week.  And that once things are done, I can take things a bit easier.

So why am I posting this instead of finishing off my odds and ends?  And getting some sleep?  I want to start some good habits that I want to carry out through the new year and beyond.  One of them is writing everyday, and moving forward on my long overdue tasks.  Hence this is today’s blog entry.  I apologize if it sounds like filler but it isn’t.  Anyways, now I really need to finish work and get some sleep.  Good night and good day!

Daily Writing

I’ve done a lot of thinking today.  About what to do next in life, and what will be the next big thing.  I feel that I should seriously back into writing in a big way.  Managing all the projects that I’d like to do will be challenging.  But I think I should try and dedicate one day of my week for a particular project.

But one thing I will do, is do some daily writing.  I should be able to manage, cause after all I am posting this even though it has been an off day.

Totally Unknown Writers Festival 2010

On Wednesday evening, I went to the 17th Annual Totally Unknown Writers Festival. As always organized by the great folks from Life Rattle Radio and originally founded by two of my professional writing professors, Guy Allen and Arnie Achtman. As with every year, great stories written and read by talented authors from around Toronto.

I hoped to read this year, but I’ll get ready for next year’s festival. I did meet up with some of my old classmates from university. And I was able to catch up with them and Guy. If you want to hear great stories of life experiences from the GTA, I highly recommend coming out to the festival.

In the Beginning of November…

A new month begins and a new twist to life. This is the first day at a new office in downtown Toronto. Not that I’ve changed positions, I’m still working as a mobile developer for Web Impact. For my coworkers, this is nothing new since they all worked at the Toronto office before moving out to Mississauga. Unfortunately the Mississauga location did not provide what we needed and so we are moving back for now.

This morning everything is a little different. Figuring out new schedules, new routes and a new location. Should be fun. Other than that I’ll still get to enjoy working on mobile coding, with all its unique challenges.

One challenge I worked on this past while is writing. Not a lot of progress on the novel. But I did manage to submit two short stories for publishing. One to the Fall issue of the Alexandrian, which should come out soon. And one to 365 Tomorrows, which will hopefully get accepted too.

Other than that I still have load of catching up on work. I still feel a bit behind. Anyways, this next stop is mine. Catch you later.