how to write computer books

Style quiz | Diversions | Economist.com

Tue, 13 May 2008 04:06:49 -0400

Style quiz | Diversions | Economist.com: Fun and quick multiple choice quiz. Pick the best-written sentences. Have a look — it will improve your writing.

Punk’s DIY ethic meant that musicians got past the suck...

Fri, 09 May 2008 11:51:10 -0400

Punk’s DIY ethic meant that musicians got past the suck threshold faster than, say, a concert pianist. You can become a punk guitarist in 10 minutes. You’ve arrived. Form a band.

After that, you have a life time to get better.

How much does a reader need to be a ‘punk’ programmer, web designer, or site builder? Can your book teach them this first, and then spend the rest making them better?

Seth's Blog: The Media markets

Wed, 07 May 2008 11:01:50 -0400

Seth's Blog: The Media markets:

Drama sells news better than fact. If you want people to pay attention, you’d better find the dramatic angle.

Any time you teach anything, finding drama will help keep learners’ attention. Even if emphasizing drama means diluting the truth, readers will learn more overall.

The Engineer, the Computer Scientist and the Toaster

Wed, 07 May 2008 08:55:04 -0400

The Engineer, the Computer Scientist and the Toaster: Good story well illustrated.

Incredible death defying video — check it out. This...

Fri, 02 May 2008 12:11:00 -0400

Incredible death defying video — check it out. This isn’t footage from Indy 4:

Originally built in 1901, this walkway now serves as an aproach to makinodromo, the famous climbing sector of El Chorro.

The best parts of this video are when the dangers seem worst and the challenges greatest. Give your tutorials a sense of danger and adventure

Don’t be cautious. Don’t say “before we can do something fun, we must do some dull stuff”. The earlier you get the action, the more dangerous it feels, the more fun they will have.

[via ElizabethN]

Covering topics in the right order

Fri, 02 May 2008 10:33:00 -0400

A big part of planning a book is deciding what order to cover things in. This is an issue when planning the book as a whole, individual chapters, or sections within that chapter.

Happily, there are three organizing principles that you can use in almost any situation:

Move from simple to complex — start with the easiest bit
Group related topics together — variations on the same theme come close together
Follow a sequence of steps — gradually build something

In most books, each of these principles will play a part — and the best structure will use elements of each. Sometimes you have to find a balance between the 3 principles.

Think about how we would apply this to a beginner’s guide to programming:

Simple to complex — you would usually start with simple concepts like variables, if-then statements, loops, and other basics before moving onto creating libraries, classes and objects, and architecture decisions.

Grouping related topics together — you would tend to cover if-then and select case close together. For loops and Do loops would probably appear together too. They are obviously related.

Follow a sequence of steps — you probably wouldn’t teach programming by going through the steps you take to develop a program (starting with design, planning the architecture, etc.) because the early steps are some of the most complex. So in the case of learning to program, you might play down this principle.

There is no such thing as the perfect order. All you can do is avoid the really bad ones. Your book will be read by hundreds or thousands of people, and they won’t all have the same learning style.

Follow these organizing principles and you will end up with an order that will be fine for most people.

5 steps to killer chapter outlines

Fri, 02 May 2008 10:13:00 -0400

Starting with a good chapter outline will make writing much easier. On the other hand, getting it right can take ages. Here are 5 key principles for buidling strong outlines.

Put background at the back. Technical overviews, ‘what is…?’ questions, and so on make for a boring beginning. Plan to cover them at the end, if at all. Most authors naturally put this at the front. Resist that urge, damn you!
Motivate at the front. At the beginning, give the reader reason to read on. Show the reader what’s in it for them. Show why it is necessary, useful, exciting, time saving, or whatever else makes it worthwhile. Tell them just how much they will acheive / learn in the chapter.
Build the middle section around practical action. The bulk of each chapter should show the reader how to do things. This could be making decisions, completing tasks, or applying principles. Most of your sections should begin with an ‘-ing’ word such as building, creating, designing, choosing, and so on.
Put major sections in a sensible order. There are three ways to order the middle part of a chapter. By increasing complexity, by logical grouping, or by process. Increasing complexity means starting with simpler topics, and getting more complicated gradually. Logical grouping means that related topics tend to come together. Process means that the chapter is built around completing a task in a realistic sequence. Use each principle to develop a sensible order for the main sections in your chapter.
Stop planning, start writing. No chapter plan is perfect. Creating a plan that roughly follows each of these principles won’t take long. Once you have an OK plan, it’s time to start writing. No plan is perfect — but you won’t how imperfect it is until you start to execute it. So have faith and get started. You can always move stuff around later.

Book writing: 3 ways to be practical

Fri, 02 May 2008 09:52:00 -0400

Readers love practical books. It’s something that all computer book publishers want to say in their blurbs, and want to see in reviews:

“Relentlessly practical!”
“No fluff”
“Hands on instructions”

Books are practical when they show readers how to:

Complete tasks — step-by-step instructions and functional references help here
Make decisions — pros and cons, factors to consider help here
Apply principles — tips and tricks, “10 ways to…” type lists are great at this.

Too many authors fill their books with information, without much thought about how to use it practically. The result is a chapter that feels like an essay, and a book that feels unreadable an inaccessible.

Always look for ways to help readers practically, and emphasise the practical implications of what you are saying. If readers don’t understand why something is useful to them, they won’t listen.

And always make sure you are helping the reader DO things, not just read about them.

Not just for fiction authors… this will help you find the...

Fri, 02 May 2008 06:17:00 -0400

Not just for fiction authors… this will help you find the time and motivation to write… NOW!

Contains advice on: finding time in your day, minimal planning, increasing wordcount and progress, and having fun.

I would love if all the authors I worked with read this…

Seth's Blog: Self promotion

Thu, 01 May 2008 04:29:33 -0400

Seth's Blog: Self promotion:

I published a book so I need you to read it vs. There’s something you need to read, so I wrote about it.

Coding Horror: Programmers Don't Read Books -- But You Should

Tue, 29 Apr 2008 11:01:39 -0400

Coding Horror: Programmers Don't Read Books -- But You Should: Jeff Atwood, interesting as always.

NETTUTS - Web development tutorials and links - Spoonfed Web Tutorials

Tue, 29 Apr 2008 04:26:07 -0400

NETTUTS - Web development tutorials and links - Spoonfed Web Tutorials

How to Start Writing When You Don’t Feel Like It

Mon, 28 Apr 2008 07:07:15 -0400

How to Start Writing When You Don’t Feel Like It: Get motivation and break writers block: “write for someone who cares”.

phpied.com » Blog Archive » Editing made easy: 6 words to cut out

Mon, 28 Apr 2008 03:48:00 -0400

phpied.com » Blog Archive » Editing made easy: 6 words to cut out:

very

really

just

quite

perhaps/maybe

that

“Typography is what language looks like.”

Fri, 25 Apr 2008 07:59:01 -0400

“Typography is what language looks like.”

Conflict is your friend

Thu, 24 Apr 2008 11:11:00 -0400

For any book or story to be really satisfying to read it needs conflict. You won’t keep a tutorial engaging for several hundred pages without some battles here and there.

Without it your writing will seem flat and either like an encyclopedia or a marketing release. Boring, turgid, put downable.

Conflict doesn’t have to mean war. The ingredients of conflict are:

Somebody has a goal
An object or person gets in the way of that goal

You then resolve the conflict by finding a way to acheive the goal anyway, for changing your goal.

The object or person that gets in the way is called an antagonist. When writing technical books, you can find these antagonists:

Other stakeholders and characters: a boss who makes unrealistic or unpallatable demands; and administrator who won’t give you the rights you need; a client with their own unrealistic demands.
The tool itself, or the computer: at times we all hate the tools we work with. Computers are fussy, systems are non-intuitive. We have all crashed our fists on the keyboard at times. Don’t praise to tool all the time — sometimes it is the enemy.
The seeming impossibility of the goal: sometimes, a goal appears tough or impossible. Build this up sometimes — make it seem really hard — and then say “but I’m going to show you how to do it anyway”.

These conflicts probably exist in the reader’s life anyway… you can have fun by acknowledging and emphasising them in your writing.

Let me suggest this… look for ways to incorporate conflict into your next chapter, tutorial or book.

Let me ask you this… what are the conflicts that YOU face when learning a new tool or building a new system?

Gone Fishin': How to Hook Your Readers With Textual Crack

Tue, 22 Apr 2008 08:13:00 -0400

Gone Fishin': How to Hook Your Readers With Textual Crack: offers 7 easy ways to make your text addictive.

Who’s on First? This is what great writing looks like.

Mon, 21 Apr 2008 12:45:41 -0400

Who’s on First? This is what great writing looks like.

First Android Tutorial Contest :: anddev.org

Mon, 21 Apr 2008 10:40:06 -0400

First Android Tutorial Contest :: anddev.org: Write a good, focused Android tutorial and win a t-shirt. Smart way for an open source site to give documentation a boost.

A Practical Guide to THE HERO WITH A THOUSAND FACES by Joseph Campbell

Mon, 21 Apr 2008 08:21:20 -0400

A Practical Guide to THE HERO WITH A THOUSAND FACES by Joseph Campbell : Chris Vogler provides the best guide to the ‘hero’s journey’ I have seen. Use this guide to plan your own plots.