I have been working every day on the linear algebra chapter in order to push them forward as much as possible before September 1st. I can’t say that it is going too well. The old cadence of one section per day seems to hold true regardless of how much effort I put into the process. I guess there is some  natural daily capacity limit for the human mind (at least mine) for the production of thoughtful written word.

This is not good in terms of having Minireference ready on time for the first day of classes. Let’s do a quick assessment right now:

• Math: 90% done.
• Physics and Easy Calculus digression: 20% done (will require 4 days)
• Vectors: 95% done
• Mechanics: 80% done
• Calculus: 90% done
• Electricity and Magnetism: 70% done (couple of days)
• Waves and Optics: 20% done (~ a week of work)
• Linear Algebra: 60% done (~ a week to go)

From the above estimates, it means that I am about 3 weeks away from a finished product. But wait! Recall that any time estimate ought to be doubled if you want to have a realistic time estimate for the real completion date. What does that leave us with? Aug 19th –2 montsh–> Oct 19th. Not to mention that I have to give a talk in Singapore in the meantime. Hmm… Not good. Shall we aim for a launch date mid-term?

Perhaps more important to the whole entreprise and this September’s market test is the support material and not the actual book content. These include:

• Book cover design (Charlotte?)
• minireferece.com website (design, pitch text, PDF sample)
• One-page condensed content flyers for Calc & Mech
• lulu.com (print) / ejunkie (pdf) purchase page tests
• facebook page for Minireference Co. ?
• Who can sell for me at McGill while I am in Bulgaria?
• Concordia sales?

Wow! That is quite a bit of things to do before September 1st. It is kind of depressing to think about all that needs to be done. I have to go into another energy level if I am to get through this. Well it is not like I have never overcome obstacles before. I just have to stay together and minimize the down-days. Keep your eyes on the product. The world belongs to those that ship!

As of changeset 135:2b29bc006dbb in the minireference repository, we have a 70% finished book. Still lacking are certain sections in E&M and Linear Algebra. After today’s reading of some of the Mechanics material, it makes me think that another pass might be necessary there too, in order to really give good explanations.

The text is the problem right now though. I would say that the main thing separating me from the v3.0 release on September 1st is the lack of figures and exercises. A figure is worth a thousand words, and so I think I really need to work on that (TikZ? scanned drawings?). As for exercises, it goes without saying that half of the learning happens while solving exercises so it would be a shame not to have exercises.

There are just about 23 days left before September 1st though. How are we going to do that?
Magic. Magic my friends. We are going to use magic, the skill I learned back in my Electrical Engineering days when I was able to put away n exams and m assignments in one week. Three weeks is a lot of time.

Let’s have a draft ready by the end of the week, then focus on proofreading and inventing fun exercises.

Today, I heard from hacker news, of an excellent website with UNIX tutorials and Perl code examples. The web-dev context is kind of dated, but the UNIX stuff is still good: UNIX hasn’t changed much since the 80’s so UNIX tutorials don’t age.

I also found an excellent piece of advice for technical writing, i.e., the teacher-student relationship:

Understanding the Characteristics of a Student

The first thing that we need to understand before we start writing about some technical issue is that our reader has a few general, stereotypical qualities which we would do well to incorporate into our documentation strategy. The following list reviews some of the characteristics which will greatly direct your writing.

• Students think that what you have to say is boring
  • Incorporate pictures into your text. If it looks fun, it is fun.
• Students are intimidated by what you have to say
  • You may be extremely familiar with your product, class library, or code base, but that is because you’ve been working with it for the last few months. Remember that your reader is probably coming at this for the first time.
  • Tell some jokes. Get things off on the right foot. Make the reader feel as if you appreciate the struggle she has agreed to undertake.
  • Use lots of metaphors to explain things. It is likely that the ideas and theories you want to get across correspond to some daily activity that your reader can instantly feel empathetic with.
• Students are unfamiliar with terminology
  • For goodness sakes, make sure to include more description than seems reasonable to you. The advanced reader can skim through it and the beginning reader cannot live without it.
  • Make sure you leave enough time to compile a good index, table of contents and glossary. If you’ve been a reader of technical documentation you’ll know that these “extras” are sometimes the most utilized resources. Nevertheless, most authors skim through them at the last minute before printing.
• Students are insightful, give them a way to send feedback
• Students learn by doing.
  • Only in theory do people learn by theory. In reality they learn by example and participation. Make sure to give them a lot of code to work through. Include the theory in between the lines. Sneak it in so they don’t realize they are learning abstract concepts.
• Students have a problem
  • Your readers did not pick up the documentation to learn about the product. They picked it up because they needed to do something with the product. Thus, make your examples useful. Make them cut and paste problem solutions. Takes some time to predict the types of things that your customers will be doing with your code and solve those problems as examples.