How to Write a Book and Not Die Trying: The Story of How I Wrote JavaScript-Mancy and Everything I Learned From Writing Two Books and a Half - Part II - Book Execution

| Comments

Hello! I’m back!

In the last article of this series we talked about the first steps you need to take when starting to write a book: The Why, the What and the whether to use a publisher or self-publish. Today we’re going to dive deep into the actual process of writing, that grueling and marathonian challenge that will suck the life out of you if you choose to venture into its muddy waters.

If you consider yourself brave and interested in writing then go on and venture forth! If you’re not you may still find a lot of useful tips into the art of keeping your focus, motivation and getting stuff done. All steam ahead!

Book Execution

The Preparations of Writing

The best preparations that you can do before you start writing a book is to already be an expert or someone extremely knowledgeable in the topic you want to write about. This will let you summon all that knowledge and experience and start writing right away. Otherwise, you’ll need to gather all your patience and curiosity and dive deep into the topic of your interest.

Once you feel that you grok the subject of your book then you are ready to start writing. You don’t need to know everything about everything at this point, there will be time to do more research as you go writing each chapter, but it is important that you have a strong knowledge in the subject to be able to write a consistent outline for the book and keep your spirits up with some early wins.

In the case of the JavaScript-mancy series I had lots of experience in .NET, C# and JavaScript, and although I didn’t know all the specifics about the ES6 Reflect API, I knew a lot of stuff that I thought could be extremely interesting to C# developers coming to JavaScript.

The Mechanics of Writing

The step by step process that I follow to write a book is the following:

  1. Write a general outline for the book. This means writing a list of all the chapters I expect the book to have.
  2. For each chapter
    1. Write outline for chapter
    2. Write without stop from beginning to end focusing on content and not as much style
    3. Review chapter focusing on improving clarity and style
    4. Review chapter reading it aloud
    5. Review code samples
    6. Write story
    7. Write exercises
  3. Ad hoc reviews incorporating improvements from technical reviewers
  4. Review complete book. Focus on clarity.
  5. Review complete book reading on a kindle. Focus on making each chapter special.
  6. Victory

Let’s dive into each of these steps.

The General Outline

The general outline of the book gives you an overview of your entire book before you start writing. I typically use the following structure:

1
2
- title of chapter
- small description of chapter content

The purpose of the general outline is twofold:

  • Give you an idea and let you reflect about the content and scope of the book
  • Shape the high level structure of the book so it is the most conductive for learning

Note that at this point nothing is set in stone, you can add/remove or move chapters around as you see fit when you start writing the actual chapters. When you are happy with the high-level structure of the book, move to the first chapter and start writing. Yey!

Writing a Chapter

When writing each chapter I follow the process I mentioned earlier:

  1. Write outline for chapter
  2. Write without stop from beginning to end focusing on content and not as much style
  3. Review chapter focusing on improving clarity and style
  4. Review chapter reading it aloud
  5. Review code samples
  6. Write story
  7. Write exercises

I start by writing an outline of the whole chapter which basically consists in a series of headlines for the different sections and subsections that I envision the chapter having. After that I start writing starting from the top.

There’s nothing more terrifying than a blank page (aside from creepy little children in horror movies), so I just start writing without being too demanding nor perfectionist. In this first pass I value the content more that I value the style or the structure. I just write and write to the end. This is super important if you want to be a proficient writer. Don’t stare at the blank page blocked, don’t stop reflecting for minutes about the perfect way to explain X. Just write, even when you know you’ll need to improve it later.

I will typically write the code samples as I need them to support the different concepts and techniques I am writing about. I will use a JavaScript prototyping tool like jsBin, jsFiddle or codepen and jump between writing and coding. Only with new APIs which I’m not familiar with or with more convoluted examples will I start writing code before writing the actual chapter.

When I complete the chapter I will typically do three review passes, the first two ones focused on improving clarity and style, the last on the correctness of the code samples.

Reviewing and Focusing on Clarity And Style

For clarity I follow some heuristics:

  • Break down big paragraphs into smaller ones. I feel that this adds a lot of breathing room in the page and makes the text easier to digest.
  • Break large sentences into smaller ones. Similar to above. If I find any large sentence I break it into smaller one separated by dots. I find that the text is much easier to follow and comprehend.
  • Choose active voice over passive voice. It feels more direct, near and conversational.

For style I do a couple of things:

  • I read the chapter aloud which helps me make each chapter more conversational. My intent is to make the chapter feel like if I was there with you explaining something in person.
  • I like to add jokes, fantasy references and quirky words to break the monotony of reading and make the book more fun to read.
  • In general, avoid repeating words in consecutive sentences.
  • Try substituing pronouns or articles for the actual words they replace. Sometimes the text becomes crisper when you do this. But other times it can become very repetitive so beware, use your spidey senses.
Reviewing Code Samples

When it comes to the code samples I do an additional pass focusing solely on them. I start by reviewing them for correctness, everything should run exactly as depicted in the code sample and then I:

  • Explain the code sample. I prefer to over explain an example rather than assume knowledge and context from the reader and make him/her feel lost.
  • Prefer small examples to larger ones. Generally, I will intertwine bits of code with bits of text explaining them step by step.
  • Prefer meaningful examples than fabricated ones. Examples always work best if they are meaningful and relatable rather than artificial, simplistic and fabricated. The problem is that finding a good example takes time. Don’t be lazy and find a good example, it will pay off. Good examples are awesome instruments for learning.
God Bless Technical Reviewers

It doesn’t matter how many times you review a chapter, how much time you spend proofreading, how close you look at the code samples, you will make mistakes.

Having a second and a third pair of eyes is invaluable. If you can, find some technical reviewers to help you ensure the quality of your book. Ideally, they will have different degrees of expertise in the topic that you are writing about and they’ll be able to give you feedback from a beginner’s and an expert perspective.

Exercises

Exercises or no exercises, that is the question! I typically don’t do any exercises that I find in programming books. At the same time, I find interactive exercises an incredible tool for learning. There’s nothing better to really learn something than to experiment with it. You may think that you’ve learned technology X by watching a video, or following a Pluralsight course but you don’t. Until you have experimented with that technology yourself, you don’t.

For the JavaScript-mancy series I decided to write exercises to reinforce all the main concepts in each chapter. It added a ton of time to the production of the chapters but I think they came out great. I like the exercises to be open ended and I only provide a solution not as the only source of truth but as one of the possible solutions encouraging the reader to experiment.

If you decide to write exercises for your book, then consider yourself warned. It will be a lot of extra work.

Reviewing Again

When I finish writing all the chapters I do two final reviews. These final reviews are extremely interesting mainly for one reason: Typically, so much time has passed since I wrote the first chapters that it feels like I’m reading someone else’s work. This distance to your own work is awesome because it gives you a more objective view and a better critical eye. It’s also great for proofreading.

First, I do a review to focus again on clarity and structure. I may do small fixes like typos or simplifying sentences, or massive changes like restructuring a whole chapter.

After this first review I am very happy with each chapter of the book and also with how the different chapters fit as a whole. Next review!

For the final final review I read the book in my kindle. This allows me to review how the book feels in a kindle and also fills me with pride. It’s weird but the book feels more like a real book on a kindle than when you read it on your computer as a pdf. In this last pass I focus on style and making every chapter pop.

By the end of these two reviews I should be stoked and proud. The book is ready!

The Tools of the Writer

To get the most out of writing you’ll need to use tools that you know, are comfortable with and that will support your writing needs. In my case, and because I love the nerdiness of it I use vim and markdown. I have a couple of vim plugins to enable a nice distraction free type of thing:

  • GoYo which centers the text you’re writing in the middle of the screen.
  • Limelight which highlights the paragraph you are writing at a given moment by dimming the rest of the paragraphs

And that is pretty much it. Vim has a built-in spell checker that you can enable with a simple command :set spell spelllang=en_US.

I use leanpub which allows me to have my books inside a git repo, write the book and chapters in markdown and every time I push an update to the repository, leanpub generates the book on pdf, epub and mobi formats and drops the generated files into a dropbox folder for me to review. I find this extremely geeky and convenient.

On Being Productive

Chances are that if you start writing a technical book like mine you will do it as a side-project. That is, you probably won’t quit your job or take a vacation to write a book. That means that you’ll write your book in the few precious hours outside of work and life. Because you don’t have that much time left to write, it is important to make the most out of that time. Here are some productivity tips that’ll help you get that book done:

  • Create a habit of writing. What does this mean? Write often, write as often as you can. The more you do something, the more you do it. It’s like a circle of virtue that feeds itself. When you create a habit out of something you remove most of the mental barriers that prevent you from doing it and procrastinate less.
  • Reduce your use of social networks. Social networks are like crack. They are extremely addictive. If you are not careful you’ll waste huge amounts of time navigating these hives of scum and villainy aimlessly and refreshing the feed. The best way to remove bad habits is to create a path of most resistance to do them. Or to create a path of least resistance to the behavior you want to encourage. Examples of these are: removing the twitter, facebook and reddit apps from your smartphone, or installing a browser extension like focus.me which works great to avoid the quick reflex of going to a social network by default.
  • Just 5 minutes. Whenever you feel tired or unmotivated try the 5 minutes trick. Just write for 5 minutes. Writing only for 5 minutes is such a teeny tiny commitment that there’s no reason not to do it. You’ll discover that once you have started writing it is very easy to continue. Making this small commitments are a great way to break the inertia that prevents us from getting shit done.
  • Try the pomodoro technique. The pomodoro technique is a simple productivity system that aims to teach you to focus on the activity at hand. It consists on breaking any task into chunks of 25 minutes of undivided attention, followed by a 5 minute break. It has great side effects like learning about yourself, how you lose your focus, the environment in which you work, gives you space for continuous improvement and much more. I find it works great when I’m feeling unfocused or when I don’t feel like doing an activity.
  • Take a break. Take a weekend off from time to time and recharge. Do something else that gives you energy and come back energized.
  • Do a sprint. After having spent some time writing your book you’ll get to that 80%/20% point when you have that final 20% to finish it, but progress will feel super slow (there’s 80% of the effort left). When you are in this situation a great way to move forward is to do a sprint. Book a weekend, take a couple of days of vacation, and get the book done. Or as much of the book done as you can.
  • Say NO to other things. If you want to complete your book, the reality is that you’ll need to sacrifice other things. You won’t be able to take a look at that shiny new framework, or have time to learn that cool programming language, or go to that conference. It is your decision but taking on other commitments will prove grueling, stressing and frustrating.
  • Some time good will have to be good enough. It is better to be done that to be perfect. Some time you’ll have to look that chapter in the eye, tell him “you are done my friend” and move forward.

If you want to know more about the productivity system that I use to get things done, then check this article where I describe it.

On Keeping Your Motivation

Writing a book is a marathon. One of the hardest things about it, is to keep your motivation and spirits up throughout the process so you can see it to the end. Here are some things that can help you keep that motivation.

  • Remember your Why. Make a point of remembering often why you are writing the book in the first place.
  • Practice visualization. Visualize how it will feel when you finish the book. Imagine having that paperback finally in your hands, and your pride, happiness and joy at seeing your book completed. Imagine one of your readers going through your book and enjoying it thoroughly. Visualize a future situation in relation to your Why. Is it to be recognized? Visualize your peers celebrating the most awesome book of all times.
  • Progress often and celebrate the small victories. Finished a chapter? Celebrate! Completed 25% of the book? Celebrate! Made your first sale? Celebrate! Don’t wait to finish the book to celebrate it.
  • Make a public commitment. We’re social animals and we’re more likely to do things when we commit to them publicly. A great way to do this is to follow the lean publishing model and publish your book before it is completed. The moment that you have your first sale you have a paying customer that is looking forward to reading your book. That’s a strong motivator right here.

Concluding

Awesome! Hope you have enjoyed this second article about how to write your own beautiful masterpiece! In the next and final chapter on this series we’ll talk about the final step of the journey, publishing your book, packaging, designing a cover, creating the printed version, distributing, sales, marketing and well wrap the series with some reflections about writing.

Have a great week!

Get the Book! Save the World!

And now is time to get the book! JavaScript-mancy OOP: Mastering the Arcane Art of Summoning Objects, a compendium of OOP techniques available in JavaScript, ES2015, ESNext and TypeScript.

JavaScript-mancy OOP: Mastering the Arcane Art of Summoning Objects Book Cover

Comments