how to write computer books

3-act tutorial adventure: my version

I have been thinking a lot over the weekend about storyboarding non fiction. Here is the structure I’m thinking of, in 3 acts:

Act 1 — the call to adventure

The reader discovers what they will be doing in the book, and finds the motivation to learn. They make a decision to start the adventure, and they…

Cross the threshold

Here the reader performs some action that transforms them: they install the software and try it out, build their first program, whatever. This results in a sense of victory and acheivement, and triggers their passage into…

Act 2a — mastering the tools

Here the reader gains mastery of the tools they will need in order to reach their goal. Each chapter is full of short, self contained hands on tasks as the reader masters different aspects of the tool or topic. At some stage they have acheived a level of mastery of the tools, and can progress to…

Act 2b — completing the task

Now the reader is ready to use all of the tools together to complete their task and acheive their goal. If Act 2a was about learning the different commands in a programming language, Act 2b puts them together to build a real program. By the end of Act 2b the reader has acheived their goal. Now they need help…

Act 3 — … living with the treasure

Act 3 celebrates the victory, but then looks at how we can care for our ‘treasure’ in the real world. This might involved looking at ‘maintenance tasks’ and other dull necessities.

A good Act 3 will often leave the reader with some hint at possible future adventures — hints of additional skills that they could master in the future (with or without the help of more books)

Book market research for Dummies

Quick ways to test if there is a market for your technical book:

• Go to Google Trends. Compare the keyword in your title to keywords for other topics that sell well.
• Check out the competition on Amazon. Look at the sales rank. Low is good. But… if there is already a book on your topic, how will yours compete? Remember — to compete on Amazon, the differentatior has to be obvious on Amazon. You can’t compete just by being “better” — people won’t know which book is better unless they read both.
• Look for download statistics: if you’re writing about an Open Source tool, you might be able to find out how much it’s downloaded. Encouraging?
• Look at forum discussions: are lots of people actively discussing the topic? What are they saying? Does it look like these are people who want your book?
• Check web site rankings: if the tool you’re writing about has its own web site, how is it doing on Compete.com?
• Search Google — are there lots of pages about the topic? Lots of pages is an indicator of lots of interest. Lots of ads is an indicator that people with money are interested in the topic too.

Always assume there is no market to start with — and look for strong evidence that disproves that assumption.

Remember that a popular tool doesn’t always mean a succesful book. Many tools are very popular, but not many of their users would want a whole book about it. Try to guess: what % of users of the tool really, really need your book?

After you’ve done this, I hope you’ll contact me and talk about the book idea! My address is to the right. —>

I can even help with the research too. :)

Comments: this blog now has 'em.

Perfect books for Han Solo and Obi Wan

Following up my previous post, here are the sort of books each mentor would ideally write…

The perfect Han Solo book:

• Is on a topic that is fun to learn about and play with
• Is on a topic where mistakes won’t matter much
• Has a confident target reader who isn’t afraid to have a go
• Deals with a big topic, and only introduces highlights / gets the reader started – leaves the reader with lots of unanswered questions but excited to keep learning

The perfect Obi Wan book:

• Is on a topic that isn’t much fun in itself – but is useful and genuinely worthwhile
• Is on a topic where the reader can’t afford to make mistakes
• The reader lacks confidence and needs reassurance
• Covers the chosen topic comprehensively

Few books meet all categories, which is why most books will borrow elements from both styles.

Setting the tone -- are you Han Solo or Obi Wan?

All books have a ‘feel’ to them — a general impression that you get when you read them. When writing, make sure you have an idea of the tone/feel you want to create.

Find a tone appropriate for:

• Reader: what sort of person is reading this book? What kind of tone will they enjoy?
• Topic: does the topic lend itself to a particular pace, level of formality, or level of seriousness
• You: how do you like to relate to people? What tone will give an authentic sense of your own personality?
• ‘The book’: is the book title or position intended to have a specific feel? Is it competing with other books on the basis of style? Do you want your book to ‘stand out’ in some way?

Think:

• Fast or steady – is this ‘fly by the seat of your pants’ or safe and steady? Many readers love both, some prefer one or the other. Everybody would prefer the book to have SOME consistent sense of pace. Emotional result: the reader will feel either excited (this is fun!) or reassured (this isn’t as hard as I thought!).
• Funny or serious – do you want the reader to find the book light hearted and irreverent, or sensible and professional. If you want to be funny, can you sustain it for 300 pages? Can you use humour in a way that readers will like and will encourage learning rather than distracting them? It’s dangerous to aim for humour – the question is really, shall I PERMIT myself to drop in humour when I see the opportunity?
• Casual or formal – do you want a friendly or professional relationship with your reader?
• Excited or dispassionate – do you love your topic for its own sake? Do you look forward to playing around with the tool to see what it can do? Or do you see it as practically useful and worthwhile, but hardly loveable?

In Star Wars, Luke has two main mentors — Han Solo and Obi Wan. He learns from both, but in different ways. If they were writing your book, how would their styles differ?

Han Solo – he talks fast – being on his ship is fun, but also feels dangerous.

Obi Wan – he talks slowly – you feel that he will always look after you. You feel safe but you might get bored sometimes.

Han Solo – he is funny – he smirks a lot. He is sarcastic and jokey. But he doesn’t say things only to be funny – he says what he has to say, but in a funny way.

Obi Wan – he is serious – he occasionally uses wit (“who’s the bigger fool…”) but it’s more to make a clever point than the make people laugh or express humour.

Han Solo is casual – you immediately feel like you’re either his friend or his enemy. He talks how he feels. Instead of “yes” he would say “yeah” or “sure”.

Obi Wan is formal – he treats everybody – friend or foe – with politeness and diplomacy. Instead of “yes” he would say “indeed” or “correct”.

Han Solo is excited – he loves flying fast, relishes chases, and enjoys fire fights. He doesn’t have a strong goal – he enjoys a never-ending adventure. He often does things because they are fun to do.

Obi Wan is dispassionate – he is focused on achieving the goal, and acts only in a way that will accomplish that goal.

"Okay, Morta. The Enterprise computer system is controlled by three primary main processor cores..."

Last night, I watced Rascals — a Star Trek the Next Generation episode.

A Ferengi, who has taken over the Enterprise (rather too easily), demands that Riker shows him how the computer works. Here’s the dialog:

“Okay, Morta. The Enterprise computer system is controlled by three primary main processor cores, cross-linked with redundant melacortz-ramistat 14-kiloquad interface modules. The core element is based on an FTL nanoprocessor with 25 bilateral kelilactirals. With 20 of those being slaved into the primary Heisenfram terminals. Now, you know what a bilateral kelilactiral is?”
“Of course I do, human. I am not stupid!”
“No. Of course not.”

- Riker, spouting gibberish about the inner workings of the Enterprise computer to Morta

Of course, the Ferengi doesn’t want technical background — he wants a step-by-step hands on tutorial.

Putting technical background at the start of a chapter is a great way to STOP your readers learning anything and making them feel stupid or threatened. Great if that’s your goal. If not, try another way.