Wednesday, January 27, 2016

Process for speed-writing a book

I recently speed-wrote a mini-book  Ray Tracing in One Weekend available on the kindle store.

I loved doing it.   This post is about the mentality and tools for this sort of endeavor.

Over the course of my career in computer science there have been many trends that I think are good signs of maturation of our discipline.  One, for example, is the rise of programming environments with heavy GUIs like xcode and visual studio.   The one I like the most is the rise of “agile” approaches (this would be a counter-trend to the GUI programming environments).   The most obvious example is agile programming methodologies.    In line with that is the YAGNI (you aint gonna need it) to feature evaluation.   The lean startup and MVP is the software business manifestation of agile.

Something that in my experience is the opposite of agile is writing a technical book.   I think this is one reason most people don’t write one.   The book I have the most knowledge of is the one I wrote with Steve Marschner on Computer Graphics.   Everything about making that book was not agile. That is ok from the point of view of “is the book good?”.   Yes, it is a very good book.   And I know from working with Steve Marschner I would like to read any book he was involved in.   But I would be surprised if he writes more.   Not because Steve doesn’t like explaining things-- he is in his element in front of a white board.   But writing a traditional book is as much about wrangling LaTeX and Adobe Illustrator as it is about explaining things.   I would call the process “epic”.
Last year I taught a graphics class at Westminster College in Utah.   One thing about the class is that half the majors were taking it so I decided to gear it toward making it a fun class that gives a feel for what graphics is all about.   This is as opposed to a class the punishes the students with the “spinach they should eat” if they are going to make a career in graphics.  I think the class was really fun.   It occurred to me that maybe I should write a mini-book on ray tracing based on the class assignments. Then I thought about the epic book writing process and said “no way”.

Over the next six months as I occasionally posted things on my blog, I realized how un-epic blogging was.   First, you can’t control the exact visual format-- different browsers and size setting make that impossible.   Second, there is no cultural expectation that the graphics design elements or the language be perfect so you can just concentrate on the information.   This is an example of an agile process.   Then it occurred to me-- why not write an “agile book”.   And what is that?

First because it is a graphics book, it needs diagrams and equations.   What is the easiest way to do those?  I considered drawing them on paper or a white board and photographing them.   Instead I used a white boarding program, limnu, to make the process more fluid.

For the code, I didn’t want people cut and pasting any code.   I am a big believer in typing it in.   But I also think seeing code is often the best way to communicate something.   So I put in screenshots of code. For the writing, google docs seemed like the path of least resistance and something very fluid.  That is the entire tool chain.

Writing the book this way was fast and fun.   And since 100% of my brain was focused on generating the information rather than fighting layout tools and getting uptight about look, I don’t think the book is any worse than if I had spent five times as long and make it a traditional book.
All in all, I think this is a good way to write some books.   Write it fast, make sure the information is right (for CS writing code as you go ensures this), and stick to a narrow subject with a well-defined goal for the reader.   After the experience I definitely encourage others to write books this way, and I would like to read them.


Unknown said...

I like what you're doing here. To me, the interesting thing is that you're trying to avoid extra work that's been pushed on authors with the decline of the traditional publication model. That decline has been hailed as "democratizing" publication, which is true in some ways, but mostly not.

Here's what I mean. In the 1960's (as I understand it), to publish a book with math and figures, you'd type the book on your typewriter (or have someone do it for you from your longhand notes). You'd leave blank spaces for equations and figures, which you'd draw in by hand. The publisher would then often hire someone to redo your figures, and they'd lay out and typeset your book to make it look great.

Then TeX and LaTeX came along, and authors realized they could make their own pages. And they did. Before long, publishers required this, because why should they pay someone when they can get the author to do it for free? So now the author had to learn LaTeX and go through the sweat of typesetting math. But the publisher would still often hire an artist to redraw the figures. My first few books were developed this way.

Then drawing tools got better, and more authors started using them, and again the publishers chose to make that all but mandatory (if you swore you couldn't make figures, they would hire an artist, but I know that at least sometimes you gave up some royalties in return).

Then indexing packages became more widespread. And so, rather than hire a professional indexer (and this is a much harder job than you might imagine, if you haven't done it yourself), that too became the author's job.

And so it went, with authors now essentially required to produce beautiful, camera-ready works, with headers and footers and footnotes and properly formatted bibliographies and on and on.

The author's job went from "write a manuscript, indicate the math, provide sketches for the figures, and let the publisher take it from there," to the far more demanding "produce the entire book in every detail."

Since most people can get the tools required, this is indeed democratizing, in that most anyone can make a professional-looking book. On the other hand, it means the author must have enough leisure (or paid) time to learn the tools, and then devote significant more time to produce all the content to a professional standard. This is pretty much the opposite of democratizing - it says only people who have a lot of available time can afford to produce a book with equations and figures that holds up to modern standards.

You've found some great ways to reduce this burden. Well done! I've taken a similar attitude in my own works, when I can. I'm now very happy to illustrate my work with hand-drawn pictures, as long as they're clear and do the job. I wish I could get away from fiddling with LaTeX, but programs like the one at are a big help.

It's interesting to me that we've gone from the author's job being almost completely about writing words and merely indicating the rest, to the author becoming a self-contained and fully staffed publishing house (with typesetter, artist, indexer, etc.), to now where you're shedding some of those tasks (e.g., pagination) and automating others (e.g., screenshots of code with automatic coloring).

What you're doing really does make it easier to write a book (not merely cheaper for a publisher to print it), and I say "Hooray!" The easier it becomes to produce quality materials, the better off we all become.

robert said...

Making figures and figuring out how to format pseudocode were my worst enemy in book writing, so I ended up largely giving up on it. I worry I could have used a lot more figures... After reading this, perhaps next time I'll allow myself hand-drawn figures, like I now love to use in presentations!

Unknown said...

I like the simplicity of your approach: getting the words and figures out without losing time fiddling with latex and 2d and 3d vector graphics creation and conversion software.

Unknown said...

Simply said, technical writing is a form of communication of specialized information designed for specific readers who need to use it for a particular purpose. You Can see more in : technical writing

Rebecca Virginia said...

Nice blog post you shared with us, thanks for sharing this.
Computer Graphics Assignment Writing Help