Category: Writing
-
Second Edition of Mastering Vim
I haven’t posted on my blog in a while. Besides life getting in the way, most of the stack the site was built on has become obsolete and out of date. I couldn’t really do much without a major refresh, which I finally managed to complete a few days ago.
Now, for a belated announcement: I published the second edition of Mastering Vim (a little over 9 months ago)!
This edition features new (charming) illustrations, updated and improved code examples, and teaches you how to use Vim9script. I’ve also removed about 30 pages of unnecessary content from the first edition—I’m getting better at writing, after all! I believe the second edition of Mastering Vim is a fantastic introduction to Vim.
I’m also pleased to mention that this edition has been thoroughly edited by Christian Brabandt, a fitting successor as the lead of the Vim project after the passing of Bram Moolenaar, the original creator of Vim, in 2023.
If that sounds interesting, consider picking it up on Amazon (unfortunately your local bookstore is unlikely to stock one).
-
How I write
I don’t blog consistently, and I’m still struggling to find my voice. I find writing difficult for many reasons, especially when it comes to identifying topics worth writing about. I want to bring a combination of passion, expertise, and a fresh perspective into a topic – which makes finding a theme to cover challenging. To top it all off, English is my third language. Getting the content to flow well is difficult, and I don’t always have the ear for it.
In contrast, I find it straightforward to write once I know what to write about. In part due to the volume of writing I have to do for work: as a technical lead at Google I routinely use extensive design documents to communicate my ideas. I also wrote a book once.
I found a set of techniques that work well for me. I don’t know if these techniques help me write higher quality material – you’ll be the judge of that. But these techniques help me express ideas from my head and onto paper. Hopefully in a digestible and entertaining format.
I never took journalism 101. Like with many things in live, I found my own way of doing things: why take an easy path, when a difficult one could work just as well?
I break down writing process into a set of distinct steps. I start with some preliminary research, write an outline, do my in-depth research, write a wine draft, turn that into a coffee draft, and finally proofread the result. I try to take breaks and get some distance from whatever I’m working on in between these steps.
Preliminary research
This is a step zero, although it might not apply to everything I write about. This is a breadth-first, “open as many tabs as computer can handle” type of research. There’s no in-depth reading at this point, and only high level information is consumed.
I picked up this approach from my wife, who is an indisputable queen of online research. I find it tempting to dig into the first source I find. Stopping myself from digging too deep helps me understand the information landscape.
For instance, when writing about financial independence in Cote d’Ivoire (a topic I know nothing about) my preliminary research consisted of: a brief review of country’s history, a list of major geopolitical events, investment landscape, and identifying trustworthy sources which could tell me more about currency stability or tax situation.
I’ve also looked for existing sources on the subject, but there wasn’t any.
Outline
This post started with an outline. An outline is crucial to pacing and identifying areas of focus. Chapter summaries in a book, outlining headings in technical documents, or putting together a bulleted list for a blog post – you name it.
Outline only needs to make sense to you, and you don’t have to use complete sentences. I started with the following outline for this post:
- I write a lot
- Quantity doesn’t mean quality
- I don’t publish most things I write
- A lot of practice with technical docs
- Outline
- Wine draft
- Coffee draft
An outline is not final, and it evolves as I write. For instance, by the time I wrote the bulk of this post, an outline evolved – something was removed, and a whole lot of things were added:
- I write a lot
- Double down on how bad I am at writing
- Quantity doesn’t mean quality
I don’t publish most things I write- A lot of practice with technical docs
- Double down on how bad I am at writing
- Preliminary research
- Write an outline (you’re here now!)
- In-depth research
- Write wine draft
- Write coffee draft
- Proofread the result
I like to keep an outline on the screen as I write, as it reminds me to write in context. I often jot down a brief outline when I have ideas about writing something: this way I don’t have to start from scratch when I sit down to write.
In-depth research
This is where I actually read through dozens of tabs I opened during the preliminary research. This is where I spend the most of my time for topics I don’t feel particularly comfortable with.
I make a point to time box research tasks. It’s easy to go down a rabbit hole when researching a topic, and there’s always more to learn the more you understand the subject. Putting a time limit on each research topic helps me stay on track.
Wine draft
Step 4 out of 6: this is when I start writing.
I found it near impossible to write without separating creative stream of conciousness from the editing process. The “wine draft” is the first attempt at filling in the blanks. The grammar can be all wrong, and the sentences don’t always have to make sense. It’s not necessary for the content to flow or read nicely.
This is where the outline really helps, because writing top to bottom is generally very difficult. Filling in the blanks under the outline however is much easier. I often find myself jumping between different headings and writing a little bit here and there under each heading.
Prioritizing cadence during this step helps, as a stable writing rhythm helps me enter the state of flow. To stay in the flow, I have a wine draft authoring rule: no sentence-level editing. Moving paragraphs or headings around is fine, but changing sentences is generally not.
That’s the goal - get as much content out as possible, no matter how much the language rules get abused. I find it easier to edit down a boatload of content, rather than struggle to come up with the missing pieces when editing.
This is the stage when I decide if the content is not worth publishing – many of my wine drafts never see the light of day.
I find accompanying wine mandatory, but whiskey or tea works in a pinch.
Coffee draft
After the wine draft is complete, I take a break. Often couple of hours is enough to create a distance between me and the text. A coffee draft requires more focus and attention. This is when the messy draft takes shape and becomes (hopefully) readable. You tell me.
I make my way down, sentence by sentence, turning ramblings of a madman into a coherent narrative. I rearrange sentences, correct syntactic and grammatical errors, and liberally remove what doesn’t contribute to the narrative. If the wine draft is particularly incoherent, I simply rewrite each paragraph one by one.
This is when I add illustrations if need be. A coffee draft is nearly the final result, barring typos and minor mistakes.
Coffee helps here, but, unlike with a wine draft, is not required.
Proofreading
The final step involves good old proofreading (unless you have a proofreader: it was great having one when working with a publisher).
I try to proofread in a different software suite, or with different fonts and colors: it helps create further distance between the content and I. For instance, I write this post in Vim using Markdown, but I proofread by reading the final preview using my blog’s visual theme.
It often helps to read things out loud too: anything you can do to change up the way you perceive the text.
And finally it’s ready to be published: ta-da! This method hasn’t failed me yet, be it for writing Mastering Vim, technical design docs at Google, or blog posts like this one. Fingers crossed it’ll continue working well for me.
- I write a lot
-
How much does writing a book earn?
I write about Vim – a modal text editor – a lot. In fact, in early 2018 I was approached by Packt Publishing – what I’ve later learned to be a “quantity over quality” publishing house. Over the next 6 to 9 months I wrote a 300-page “Mastering Vim”.
It was a stressful endeavour, with a publisher rushing to meet internal deadlines and eventually sending an unfinished draft to print. There were many highlights too, like actually cranking out 300 pages of material, or getting to work with Bram Moolenaar – the creator of Vim himself. Now that a few years have passed and the book is at its 3rd edition, complete, and re-released – I’m a lot more happy with the result.
I can write a whole other essay about my experience working with the publisher, but that’s a horror story for another time.
I didn’t write to make money, but it’s nice seeing a couple of hundred dollars trickling in every quarter. Putting together spreadhseets is my favorite past time, so here’s a breakdown of my earnings from the time I wrote a book with Packt.
As of April 2021, the English version of my book has 14 reviews on Amazon averaging at 5 stars (that’s more than I would hope for), which likely helps keep the sales at a somewhat of a steady level.
I was signed into a default “16% of net receipts” contract, with a $2,000 advance given out to me. The advance was split into 5 milestone-based installments: the first preliminary draft, 6 preliminary drafts, the remaining preliminary drafts, the final drafts, and the publication. Although I didn’t urgently need the money, and the publisher may have just sent it as a bulk $2,000 payment after the publication.
Eventually I received a PDF for the first quarter of my book being sold… And here are the financials for Q4 2018:
Print # Print $ E-books # E-books $ 10 $55.50 274 $307.70 A whopping 363 dollars and 20 cents in royalties! I didn’t really think anyone would be interested to read the book, so seeing 284 copies sold I was pretty ecstatic!
Selling printed books seems to pay $5.55 per copy, while e-books only bring me $1.12.
Now I didn’t see any of that money, since I would have to “pay back” the advance. I know it’s called “the advance”, and I knew that I won’t be getting that first check in the mail – but it sucked a bit nonetheless.
After that I received some great news – my book was going to get translated to Japanese! During my last trip to Tokyo I made some friends who were interested in Vim as much as I was, and one of them - Masafumi Okura - decided to translate “Mastering Vim” into his native language. The legend found close to three dozen mistakes in my book too, and is solely responsible for the third edition of Mastering Vim!
Turns out the translation rights are expensive, and I’m getting my cut as well – $1,586.26! That’s more than the first quarter of sales!
Packt advertised my book for a few months or so, but they seemed to have quickly lost interest. I received my first 5 star review on Amazon though, which was great! I spent the next month refreshing Amazon reviews daily, after realizing that to be a path to acquiring a mental illness.
2019 came, and here are my next 4 quarterly statements:
Quarter Print # Print $ E-books # E-books $ 2019 Q1 29 $141.89 202 $337.49 2019 Q2 15 $77.53 71 $194.26 2019 Q3 19 $100.09 57 $207.68 2019 Q4 23 $118.55 117 $255.17 I sold 86 print books and 447 e-books in 2019. You can see the higher numbers correspond to seasonal sales. Notice the prices for Q3 and Q4. E-books sold in Q3 pay me as much as $3.64 per copy, while in Q1 it’s a meager $1.67 per book. Print edition payout stays much more consistent.
Altogether, I earned $1432.66 from my first full year of selling “Mastering Vim”.
Here are my 2020 earnings:
Quarter Print # Print $ E-books # E-books $ 2020 Q1 26 $131.61 112 $414.12 2020 Q2 22 $106.67 77 $379.61 2020 Q3 26 $141.17 74 $325.97 2020 Q4 45 $236.69 166 $458.07 That’s $1,533.38, a $100 more than in 2019. The patterns seem rather predictable, with Q2 and Q3 being slow, and Q1 and Q4 displaying a noticeable spike.
Finally, Packt offers service subscriptions – I believe the subscription is for the courses they offer, but I can’t say for sure. Payout per subscription is small, and I’ve earned $158.10 over the 9 quarters since publishing “Mastering Vim”.
Across $3,329.24 in book sales, $1,586.26 in translation fees, and $158.10 in subscriptions, this adds up to $5,073.60 over the 2+ years the book has been in print. Looks like it can make for a decent supplemental income if you write enough books, but I’m saying that based on a sample size of one.
Throughout this time, my earnings per copy average at $5.16 for a print, and $1.93 for an e-book (using weighted averages for quarterly sales).
And here’s the last number in this post – this one purely for fun. Based on the 16% royalty rate, Packt probably earned $31,710 from “Mastering Vim” so far.
-
My book has been published!
Over the past six to nine months I’ve been working on a book - Mastering Vim. Mastering Vim is a passion project which is meant to take the reader (you) from zero to a hero (future you): from knowing nothing about Vim, to becoming a power user. I cover many of Vim’s mysterious commands, philosophy behind the beloved editor, configuration tips, a plethora of community created plugins, as well as creating your own plugins.
Mastering Vim was written with support from Packt Publishing and was kindly reviewed by Bram Moolenaar (website) - the creator of Vim. Many people made this book possible, including VimConf Japan crew, who kindly hosted me earlier this year. Thank you to everyone for making Mastering Vim happen!
Give it a read and let me know what you think, Mastering Vim is available on Amazon!
P.S: This post, like many others, is written in Vim.