The Wizard Logs - Part I - The Adventures, Glory and Misfortunes of Writing Wizards Use Vim

This article was originally posted in barbarianmeetscoding.com.

As soon as I announced Wizards Use Vim at such an early stage of writing I started thinking about the best way to involve the community of readers in the writing and development of the book. Should I send email updates every time I publish a new version? Should I do it biweekly? Monthly? Should I wait till the book is ready?

Part of what I wanted to do with this book, and following the spirit of an article I wrote recently called Don't Give Up! Keep Iterating, was to show how much work goes into a book. And specially how an ugly, gross, chaotic ball of mud can slowly be transformed into a beautiful sculpture through iterative work.

This is the format I settled for: The Wizard Logs! In this bi-weekly series I'll share with you my adventures, glory and misfortunes of writing this new book on Vim. I'll give you an update of the progress of the book, ideas I've been considering, things I've been pondering about, obstacles I had to avoid and dead-ends I smacked my face into.

First, it was super heartwarming for such a weird book to have such a nice reception. This was almost entirely due to the awesome and encouraging dev.to community. There was a lot of people interested and enthusiastic in reading the book at this early stage and providing feedback. In fact, there's been great feedback that has helped me improve the book already, which has lead me to add a chapter to recognize contributions in the book. If you've provided some feedback then go take a look.

Over the past week I've spent most of my Dad free time writing this book. And in the spirit of LeanPub I've published about ~20 new versions of the book with lots of improvements and new content:

• Shaped and reshaped the structure of the whole book. Splitting, merging and moving chapters around to where they make more sense. More of this coming in the future for sure
• I've followed some great advice from Arthur Zubarev about dividing the book into parts instead of following a monolithic approach. We had the same realization at the same time :D. It was great feedback! The book now has three paths: Apprentice, Master and Grandmaster to give you that awesome sense of completion and achievement after each part.
• I've spent a lot of time in the introductory chapters of the book and reviewed and thoroughly improved:
  • The preamble and the introduction
  • A Taste of Vim
  • Here Be Dragons, a chapter on the biggest pitfalls when learning Vim
  • Getting Started With Vim, a chapter to setup your Vim development environment
  • Tips for learning Vim more effectively
  • Note that these are all working titles and they'll be shaped into their nerdy form as the book evolves
• As of today I'm working on the first chapter on actual Vim Vim learning which takes you through opening Vim, opening and creating files, saving and quitting and so forth, which is the most basic stuff before you can get started with the interesting parts
• At this point I'm focusing mostly on adding content more than in quality and style. And I'm not thinking so much about the fantasy theme of the book while writing. That will be a refinement when all the content within the book is complete. But the truth is that sometimes it comes out. Sometimes it comes out waaaay too much and is out of control:

There are different paths that you can follow to get started with Vim, and each corresponds with different factions within The Order of Vim. Each with their own idiosyncrasies and approaches to using Vim, some of them purists, some others pragmatists, but all tied by the love and awesomeness of Vim.

The factions are in constant turmoil, some will rise, some will perish and others just remain through the ages. These are the most significant ones today:

The Factions

The High Arcanists of Vim represent the biggest and most ancient faction, filled with its own subfactions and groups. They are the followers and users of the original version of Vim, kicking ass since 1991. It is the most stable choice, it can run on a terminal and it provides support for a very thin GUI layer via GVim and MacVim. It's actively developed under the direction of The Benevolent Supreme Archanist Bram Moolenaar and saw the latest significant release in May 2018 with Vim 8.1 and support for an integrated terminal. You can follow their exploits in the vim mailing list.

The Neovim Witches and Warlocks, a faction which broke away from the High Arcanists with a vision in mind. To refactor the original Vim and make it more maintanible and approachable to new contributors. And thus came Neovim. Neovim has risen as a modernized Vim alternative faithful to the ideas and essence of the original. Neovim itself only supports a text interface but it is designed as a platform that can be consumed by other graphical editors (such as Visual Studio Code or Oni). It's actively developed on GitHub.

The Bards, Filis and Skalds who prefer the pragmatism of using Vim Plugins in modern editors are a minor faction. Vim is so awesome that lots of other popular editors support some kind of Vim-like mode. This is a popular choice for software developers that value the productivity boost of using Vim but enjoy the great out-of-the-box experience of modern popular editors. Some examples of editors that support this type of hybrid setup are:

• Visual Studio Code with VSCodeVim
• Atom with vim-mode
• Visual Studio with VsVim
• Sublime Text with vintage mode
• WebStorm and other IDEs based on the IntelliJ platform like IntelliJ IDEA, PyCharm, Android Studio, etc... with IdeaVim

The Oni Alchemists are a very obscure minor faction whose members experiment to achieve the impossible: Combining the best parts of Vim and modern editors into a single editor Oni to rule them all. Oni is a graphical editor built with React and TypeScript which uses Neovim behind the scenes to give you all the power of Vim but still aims to provide a great out-of-the-box experience. At present it is in very early stages but I think it is worthy to be aware that it exists and to keep an eye out for how it develops.

Wizards Use Vim

I've also been creating some art drafts for the book. These are versions 0 where the goal is to reflect an idea or the spirit of an idea in a drawing. Here are some of them:

Some cool ideas I've included into the book thus far:

• Talking about the community of Vim users and not only about Vim core features
• Having the book be quite pragmatic in how you approach Vim. The book recommends you to use Neovim/Vim to learn Vim and Vim-like editor/IDE plugins to practice what you learn in your current editor.
• Exercises where you can practice the use of Vim.
• Journaling. Instead of providing summaries at the end of the chapters. You as a reader have some homework to do. To journal and write these summaries yourself about what you've learned using Vim.

Summarizing what you've learned at the end of a chapter is a great indicator of the quality of a book. But in this book we're going to do something better. We're going to journal, and you are to going write a summary of what you've learned as you read each chapter using Vim. You're going to write down what you learn of Vim with Vim, this is gorgeously meta. Aside from the meta-awesomeness there's more advantages:

• You'll be able to see how much you learn on each chapter
• You'll consolidate the concepts you've learned
• You can reflect on how you can incorporate the things you learn in you current workflow. Is this approach more effective that what I am currently doing?
• You'll be able to use it as reference later on

Wizards Use Vim

Things that concern me right now:

• The introduction been way too long
• The online reading experience in LeanPub is not very pleasant (personal opinion). I'm considering creating a separate website where you can read the book online. This was part of my plan all along but I may do it before I had in mind.
• How the heck am I going to fit in a Fantasy story within the book (it could be in the companion game??)

If you've downloaded the book and are wondering whether or not to read the book right now (I have several readers ask me that very question) I've got an answer for you. It all depends on what you want to get out of this book:

• If you want to tag along and experience how a book gets made and is slowly improved over time, provide feedback that has a bigger impact then read the chapters from Proposal or Draft onward.
• If you want to read a version as closer to the final version as possible and still would like to provide feedback and impact the book then Candidate and Finished are the ones for you.

Wondering what the heck proposal, draft, candidate and finished are? They are just names that represent the state of maturity of each chapter within the book. Their goal is to make readers aware of this so they can decide whether they want to put up with early drafts or not.

And that's all I have for now. Until the next time! Take care and be kind to the people around you. Hug!

P.S. If you're interested in more specifics of my writing process then take a look at this series I wrote about writing books.