“The Yii Book” version 0.5 Update Posted!

March 4, 2013
The Yii Book If you like my writing on the Yii framework, you'll love "The Yii Book"!

Over the weekend, I posted an update to “The Yii Book“. This is version 0.5, which means I’m halfway there. This is about the time I was hoping to have the book done. So much for good intentions. With that in mind, my sincerest thanks to everyone for their patience. I know this is taking longer than we’d all like, but I’m doing my best and very much appreciate the understanding on everyone’s part. It’ll get done, I promise. And trust that “The Yii Book” is not taking a back seat to anything as far as my work goes these days.

As for this particular update, it started innocently enough. I wrote two new chapters: one on authentication and authorization and another on widgets (Chapters 11 and 12). Those are good, useful chapters, I think. Almost 80 pages of new material, making it the largest update thus far, bringing the total page count (as a PDF) to over 300 pages.

Then, I thought “You know, I wasn’t pleased with the quality of the 0.4 release, so why don’t I take a bit of time to polish this thing up a bit while I wait to hear back from the tech editors?” The tech editors do great at providing feedback, but it still takes them a couple of days. And, as I said, I didn’t think I was attentive enough with the 0.4 release, so re-editing the entire book to this point would be a good idea. And that process would allow me to go back and add internal links to chapters that have since been added (e.g., I wouldn’t have linked Chapter 8 in Chapter 5 when Chapter 8 hadn’t been published yet).

Also, while I was at it, I thought it would probably be a good idea to re-test all the code. Re-testing also allowed me to provide new, updated code as a download. And with the various font and margin changes I’ve made since the first release, sometimes existing code is too long, so I thought it’d be beneficial to revisit all the code to make sure it breaks properly and doesn’t run too far into the margins.

And…while looking at the early chapters, I thought the images were a bit blurry, so why not re-take every image, too? And some of the images were too big, so I should resize those. And some material could benefit from having additional images, both to break up the visual pages and to clarify points being made.

As you can see, a simple idea quickly expanded to a lot of work. All of this work took quite a bit of time (about a week and half), but I think it was useful, both in terms of the quality of the existing material and how I go about writing the rest of the book.

Oh! I did something wonderful. Beautiful. Really sharp. I finally figured out how to format all the tips, notes, and warnings a bit differently so they really stand out from the other text. Oh, it was nice. A thing to behold. At least I thought so, what do you think?

"The Yii Book" Tip Formatting

You see: I’ve been making notes along the way about things I’d like to figure out (in terms of formatting, functionality, etc.) before I say the book is done. One of those desires is to format tips, notes, and warnings so they stand out from the rest of the text. After much research and experimenting (and more learning about LaTeX, which is used to create the PDF), I came up with the above look. I like it. Notes would be similar, but blue; warnings would be red. I figured out how to make that happen in LaTeX; it was then a matter of changing all the MultiMarkdown source code to allow me to create the proper LaTeX. While re-editing the entire book, I made all the formatting changes to support this new look.

Finally, at 7pm on a Saturday night, I had edited 313 pages, including the two new chapters, re-tested all the code, and re-took about 3 dozen images. And then I exported the PDF, and it kind of worked, but I had to fix a few minor things. (Note: it takes a long time to even scan 300 pages for obvious problems.) And then I exported the PDF one last time, and looked at it one more time. And…it was a big mess.

Yuck. Ick. It was working, and then it wasn’t. Some tips et al. were formatted, others weren’t. At 7:30 on a Saturday night. And so, as I needed to get the update out, I had to forgo those formatting changes this time around. My beautiful tips and such! Fortunately, thanks to the formatting changes I made, it was just a matter of doing a search and replace to undo the formatting changes. And I’ll still be able to re-implement them later, when I can. So all the effort wasn’t wasted per se, but the fruits of my labors are nowhere to be seen today. Drat.

I always knew that self-publishing this book would be a learning process, an experiment. One lesson I’ve learned already is that when self-publishing, it’s easy to spend hours getting secondary things to work, or having things not work at all. These time-spenders (or time-wasters) are the sorts of things that would not be my problem if I used a traditional publisher. In short, a lot of my time is being spent not writing. On the other hand, almost all the money earned is now mine. But so are the delays. Well, those belong to use all!

But I’m learning. And the time spent learning about LaTeX and the secondary stuff will reap rewards if, or when, I go to self-publish another book.

In the meantime, I’ve got more writing to do!