how to write computer books

Introducing concepts: the problem, the dreadful old way, the wonderful new way

You will often, as a computer author, need to introduce some new important concept to the reader. In the first chapter of a book you might need to introduce a concept so complex and important that it’s going to take the whole book to explore fully.

Often these introductions can feel like boring encyclopedia articles, with dry academic phrases like:

• In general terms…
• … it can be considered that…
• … can be defined as:
• … is thought of as …

I am sure you have tried to read material that seemed to consist entirely of phrases like that, and nothing at all for you to latch onto an understand. If you’re lucky you put the book down or went to sleep. If you were unlucky then you had to stuck at it, and were found sobbing several hours later at the injustice of the world.

There is a much better way to introduce a new concept or idea to the reader, and it has three parts:

• Bring up the damn problem! Ever heard of ‘a problem looking for a solution?’ Before a reader can understand a new concept, they need to understand why it exists. What problem does it solve? What gap does it fill? You should describe something that the reader can immediately see is worth doing. You can do this either in general terms (‘Businesses often need to…’) or, for extra complex ideas, using a specific example (‘Imagine that a business needs to…’)
• Show me the wretched, lousy solution I would be stuck with if your new concept didn’t exist. Most problems have existed for a long time — the big ones anyway. Most new concepts solve old problems in a new, better way. Describe the ‘old’ or typical way of solving the problem — highlighting all of the painful inadequacies of the solution. By the time you have finished the reader should be sobbing — not because they can’t understand, but because they DO understand and they are recognizing just how terrible the problem is.
• Relieve the pain — by showing how your new concept, tool, or method fixes all the above problems. You can now introduce your concept as a ‘magic pill’ that will solve the problems the reader has just been reading about. How the new method or tool gets the job done without the pain of the ‘old way’.

Next time you find yourself writing material that reads like Wikipedia, see if you can apply this technique.

Take a look over this post and see how I have followed this 3-part pattern myself…