About Me

The Most Difficult Thing I've Ever Done - Writing a Technical Book

I just recently finished writing the second edition of my book Learning Swift - Second Edition and I have to say that it was the most difficult thing I have ever done. I have enjoyed writing ever since I was a kid so when I was approached by a publisher to write a book about learning the Swift programming language, I was very interested. However, even though I did a little research into other peoples’ experiences, I was utterly unprepared for what it would be like. Now that I am done, I would like to share what the experience was like to hopefully help others who may be presented with the opportunity to write their own technical book in the future.

When I was approached, I had just recently gotten more serious about writing on this blog. I was working as an independent contractor and I was spending a lot of time learning as much as I possibly could about Swift. To do this I spent a lot of time on Stack Overflow answering questions about Swift and I was even able to start developing production apps using Swift. My blog was a place where I could solidify what I learned. This whole experience was extremely enjoyable to me so when someone asked me to write a book for them it was not hard to convince me.

Up until that point I had done virtually all my writing on my blog except for a couple articles that had gotten published in UX Magazine. The magazine experience gave me a quick view into what the editing process is like. With those under my belt, I felt I had a reasonable expectation of how much effort writing a book would be and I also thought the publisher would help me along. I knew it would be difficult, but as it turns out, I drastically underestimated it.

One of the biggest things the publisher helped me with was creating structure for my work. They seemed to have a very practiced process in which they produce their books. The first thing they asked me to to do, before we even finalized our contract, was to develop an outline for the entire book. Not only did I have to break down a very large topic into a series of logical, ordered, and detailed chapters, but I had to come up with who my target audience was. I thought they had a vision for where this book would fit into their lineup of books but it seems this was not true. In reality, they were very flexible as long as it was about this up-and-coming language. Being ambitious, I decided I wanted to support both beginners that have never programmed before as well as experienced programmers from other languages. The hardest part was deciding on an order for the chapters. So many topics in a programming language are intertwined and dependent on each other. Many times I had to ask myself “How can I teach them about topic B without them already knowing topic A; but then again, can I give them a quality understanding of A without already knowing B?” In the end I came up with the order and breakdown that I thought was best and required the fewest negative trade-offs.

The other thing they wanted from me with the outline was page counts for each chapter. When I saw that, I thought, “I’ve never written anything longer than a blog post, how am I supposed to know how many pages, of some unknown formatting no less, a certain topic will take?”. I ended up asking them how many pages a book like this generally was and then I split those pages up among my chapters based on how long I thought they would be relative to each other. This felt oddly similar to estimating work on a clients project which is easily the worst part of doing contract development. However, to cheat time in this story a bit, my estimated page counts turned out to be amazingly accurate, at least compared to my expectations. Also, I did end up rearranging a few chapters once I got to actually writing them, but in general the outline remained quite stable.

Anyway, once the outline was approved they sent me a proposed schedule for my writing that gave me somewhere between 1 and 2 weeks for each chapter depending on the number of pages I had specified. They asked me to approve the schedule to which I asked myself again, “I’ve never written a book, how am I supposed to know how long it will take me”. I ended up just approving it because I figured they have way more experience with this process than I do. As it turns out, this was a painfully optimistic timeline. I got the first few chapters done on time but in the end I was supposed to finish the first draft of the book by the end of December, 3 months from finishing the outline, and I didn’t end up getting it done until May making the first draft process 8 months instead of 3.

There are many reasons that it ended up taking me so long. The most obvious might be that I was trying to fit writing into my already busy life with my contract development, my own app development, blog writing, continuing to learn more about Swift, and some amount of social life. The first thing that went out was blog writing. I just didn’t have the bandwidth or willpower to write for two different mediums about similar topics simultaneously. In fact, this is my first blog post since I started writing the book in October of 2014. I flat out refused the book ever taking precedence over my clients work but it quickly derailed my own app development. I also tried very hard to not allow my writing to get in the way of doing fun things. I didn’t think I would maintain my sanity without being able to relax and let go at times.

However, this was only part of the problem. First, I underestimated how hard it would be to come up with quality code examples. From the beginning I set very high standards for myself to come up with practical but concise code examples that not only represented real world problems, but represented as many genders and races as possible. As it turns out, this is nearly impossible. Real world examples are inherently complicated. They aren’t solved with single concepts and they cannot be describe concisely. I should have realized this much earlier because that is actually a major problem in programming itself. As programmers we often don’t fully understand a problem before we try to solve it. This almost inevitably leads to bugs. In the end I did the best I could and tried to stick with my original goals. Sometimes an example idea would just click and work out perfectly but most of the time I spent hours coming up with, updating, and re-updating different examples. Even with relatively minor ones I spent time searching the internet for things like representative names. Sometimes, after I would complete an example and begin to write about it, I would realize something significant was off or there was some aspect of the example that was using an aspect of Swift that I had not explained yet. Sometimes I would give in and just try to explain that smaller feature on the spot, but a lot of the time I had to throw out the example and start over. I think it takes an incredible amount of empathy to write a book for an audience that is not yourself, even if at one point in your life you were that audience.

The other really hard part of the writing was trying to keep the content engaging but concise. It was very hard to include all the information I needed without rambling on forever or making it feel like an owners manual. Ultimately Apple already had its own book about Swift and I wanted mine to have some personality and to have a clear point of view. I wanted to teach the technical features as well as the more artful side of programming.

However, all of these problems were ultimately small compared to the last one: motivation. All of these problems fed into the motivation problem, but ultimately I was so far off schedule because I largely lost the will to write the book but at the same time didn't want to give up on it. The best I can liken it to is doing a hard workout. You keep pushing yourself to complete the next set. Each set becomes harder and harder until at some point you break and just can’t complete it. At this point you need to rest before you can try another set but as you rest it starts to feel good and becomes very hard to motivate yourself to finish the workout.

I consider myself to be a relatively gritty person, but I have to say one of my biggest problems is that I tend to avoid doing unpleasant tasks. As I continued to write it became more and more unpleasant. I felt horrible that I was so far behind schedule and that just made me fall further behind because I didn't want to think about the thing that was making me feel bad. I also often found my creativity reserves empty and they took longer and longer to refill. It sometimes got bad enough that I couldn't even do real work let alone write.

Ultimately the only real compelling reason I had for slogging through the process was that I had already committed to finishing it. I really don't like quitting. Based on my research I didn't expect to make any money from the book because technical authors rarely do. I was also doing it because I thought it would help get new clients and potentially get my name out there in the developer community a bit more but ultimately, while I want to have an impact on the world, I don't care much about notoriety.

To try to fight through this lack of motivation I tried a few different tactics. At times I would go on walks for hours and I use the tiny keyboard on my phone to write extremely detailed outlines. I also tried setting very short term time goals, completing one page at a time but that just made the process feel even more painful. As one of the more classic recommendations, I would also update friends and family about my progress to hold me to my goals, but that often just created more negative pressure. Lastly I tried writing all of the example code before any actual writing for a chapter because I thought it might help to get the hardest part over with first. This worked relatively well until I realized I needed to deviate from the examples and ended up needing to come up with some new ones and throw some other ones out. In the end, the novelty of these approaches helped some but I only finished the book by gritting my teeth and fighting to get one word at a time on the page. Sometimes I had to go back many times to make a sentence coherent because I couldn't even complete a whole sentence at once.

After I finished the first drafts, the editing phases began. I really had no idea how many editing phases there would be and I didn't have the heart to ask. Editing wouldn't have been nearly as painful if I hadn't been so burnt out by writing the first drafts. Ultimately the first phase was responding to and I incorporating feedback from another developer the publisher hired to review the book from a content perspective. Then there was a technical editing phase for improving the language and finally a phase for approving the final layout of the book. For the final phase I actually printed out the entire book and made edits with a pen, scanning each page back in with an app on my phone to send it back to the publisher. Each phase included me carefully rereading the entire book checking if anything was missing or if there were any improvements I could make to the writing. In the end, including the second edition of the book, I've probably read my book cover to cover somewhere between 10 and 20 times.

Almost immediately after I approved the final layouts Apple announced Swift 2 with some significant changes and the publisher requested I write a second edition. Based on my experience with the first edition I was very tempted to say no, especially considering that I had designed the book to be at least somewhat future proof by talking about the art of programming instead of just the technical aspects. However, for my own sake, I didn't feel like I could consider the book complete without doing a second edition. So I reluctantly accepted. Importantly I insisted the next edition not be called "Learning Swift 2" as the publisher requested because I want to be clear that the book would be relatively future proof and not tied to the specific version of Swift; I didn’t want to write another edition when the next major version of Swift was inevitably released.

The second edition wasn’t nearly as bad as the first. I had to make some changes to each chapter ranging from minor code updates to feature additions and removals. I also had to add an entirely new chapter but working on the second edition felt much more like the editing phase of the first edition. The most annoying part was making sure the screenshots were all updated to properly reflect the latest version of Xcode and Swift. I did end up falling a little bit behind schedule again, but not nearly as far as the first time around.

The second edition was just published so I don’t know what the response is to it yet, but the response to the first was actually quite positive. It currently has 6 reviews on amazon all 5 stars and very positive except for one. The last one was 4 stars because the book did not incorporate the changes in Swift 2. Not much I could do about that other than writing the second edition. However, like I predicted, the book hasn’t even come close to earning enough royalties to exceed the advances that I got. For those of you not familiar with how that works. I got paid advances for completing different parts of the book and now that the book is published I get a small portion of every sale. However, I don’t get paid for those portions until they exceed the amount I was already paid. I got additional advances for the second edition so I don’t have any expectation of ever getting paid additional royalties. If that ends up being true, I got paid some fraction of a dollar per hour for writing these books.

On the positive side, the book definitely seems to garner me respect from anyone I tell about it. It is actually somewhat odd to me how much people respect someone who writes a book even in this digital age where it is becoming easier and easier. Part of me would like to think that it is because it is indeed still very hard to do, but I’m not sure that is the significant part of the story. Either way I certainly cannot complain about those positive effects.

The book also helped me learn a more solid foundation of Swift. In the process of coming up with a way to explain many of the nuances of the language, it improved my own understanding of the concepts. I have even referenced my own book from time-to-time when I forget the details of a more obscure feature. However, I have to say that the biggest reward I got from writing these books is the personal satisfaction of having completed something that was so difficult for me. There is great value in simply building my grit muscle.

That ultimately leaves the big question: “knowing what I know now, would I still have written the book and would I do it again?” The short answer is that yes, I would still have written the book. However, while I don’t like thinking in absolutes, I can’t imagine ever agreeing to write another technical book again. I am very grateful for the opportunity to learn more about writing and push the limits of what I can do, but I can’t envision getting nearly as much out of writing another book. I also know now that writing books is not something I enjoy. For now, I will stick with things that I love to do: writing blog posts and, most of all, developing apps.