Writing first programming book

Question

I was recently asked if I was interested in writing a book for a pretty reputable publisher, which of course I accepted. I am not a writer by trade, I am a software developer with some technical writing training. The longest thing I have ever written is a dissertation on distributed computing, which is hardly the same as a book. Of course, this book is about a programming topic and needs to be instructional and informative. My problem is how to get started; I have been sitting at my computer now for about 3 hours and have re-written my introduction about 25 times now.

I am using Scrivener as my writing tool, which I have used for other reference-type works but for some reason I just have nothing in my brain to get started, my cork board is totally devoid of notes! I don't know what to do and I am feeling totally intimidated! Does anyone have advice for a first time book author to get started? I would be interested to know what your process is for getting started and how you organize thoughts!

Answer 1

Close the intro. Promise yourself that you will write it last.

Start a blank Scrivener page.

Start writing down everything that comes into your head about the topic. Follow your thoughts wherever they lead, but make each thought a new line. Don't organize; just write.

When you run out of steam, go back to the top of the list, look at each thought, and see if it generates more stuff.

Keep doing that until you can't think of more stuff to add to the list.

Now that you have a list of stuff, start grouping it. Since I know squat-all about programming, I'll use gardening for my example.

• Group A: planting
• Group B: weeding
• Group C: harvest
• Group D: insecticides
• Group E: types of plants
• Group F: organic
• Group G: color
• Group H: season

and so on. Just put the letter (A) in front of any statement to do with planting.

Make new pages for each of the Groups. Copy everything with an A to the A:Planting page. Copy everything with a B to the B:Weeding page.

The lovely thing about Scrivener is that you don't have to put stuff in order yet. So once you have all your F:Organic statements together, just start writing. Do an info dump of everything you know about Organic Gardnening. When you run out of stuff, go to whatever topic strikes your fancy next.

After a while, you will have enough information to see how your book should be structured, or you can find an editor who can help you organize everything. You can drag your pages around any way you like.

The important thing is to get it all typed out. You can rearrange once you've gotten it on the page.

Answer 2

I wrote four such books. My first one was 750 pages. The others ranged from 250-400 pages each.

My technique was to budget a particular number of pages or a particular amount of time each day to write.

For myself, I found that if I wrote more than about 4 pages per day (6 on a good day, it varied), I would quickly get burned out.

That's 2000-3000 words.

For the general structure, I wrote an outline. It doesn't have to be very detailed, just enough to guide you along.

Don't write your introduction until you are finished. I always wrote that stuff last.

Don't bother with perfection. Your publisher has copy editors, technical editors, and so on for a reason. Let them do their jobs. On the flip side, remember that they are not programmers, and when you use words like "OR" as a verb, you will confuse them.

Find a part that interests you, and write it to get with your own flow.

There are less interesting parts to write. Power through them. Do not allow yourself to get to a more interesting part without first going through a less interesting part.

Sometimes, even when trying to budget per day pages or words, there will come some days when you just can't write 2000 words. You try your best, but can only squeak out 1000. That's OK. However, do not make the next day have to be a 3000 word day to make up for the lack, or you will reach a point when you need 10,000 words, which is nearly impossible to make good content for, and it'll overwhelm.

If you have a light day, spread out the shortage over 5-10 days. If you short by 1000 words, add 100 words per day until you make it up.

Take days off. Seriously.

Also, if you get through your budgeted words or pages, and feel like you can double it, force yourself to stop and not write anything until the next day. Trust me on this. You can write a little bit extra, about 25% or so, but don't double. Burn out city.

Answer 3

In the initial stages I think you have to free yourself from the notion that you are meant to be producing anything that will resemble your finished book.

As you are writing a non-fiction volume you will, of necessity, exist in an eco system of non-fiction works which surround the topic of your work. At this stage it is not inappropriate to re-read and examine some of the books that contain the ideas which make up the basis of your own work. You should annotate your reading, provide references to the other work and then make notes about what your volume will eventually say upon that topic. (This is also a great time to note the structure of the book that you are reading for any tips, make more notes e.g. "I like the structure of Volume X but the range of topics in Volume Y is closer to what I will be covering".)

If you do this work thoroughly you will probably end up with between 20k and 50k of foundational notes. Organise these into a rough structure that you would imagine your volume following.

Now you have a structure and a basis. Examine the notes and expand upon them until they cover what it is you want to cover in your book. This should get you to about the 75-140k mark depending how much you expand.

If you have written too much now is the time to edit. In fact once you have this ungainly mess of note taking and explanatory text editing is essential. Be careful, look for ways to cut down the verbiage. An original reference may turn into a footnote, it may become a quotation integral to the text. Or you might remove the specific reference and just leave the notes.

Anyway, that's a lot further than how you start. So I'll leave off there.

AT HEART: Remember your work cannot and will not exist in a vacuum. The first step of the journey is always to work out where it is you are starting from. So before you write, organise your thoughts, read, take notes, prepare.

Answer 4

I've written a dozen of these. Nowadays what works best for me is mind mapping. Similar to Lauren's suggestion, I write down everything about the topic I need to and want to cover in a mind map. (Give MindMeister a try.) Start grouping things into major topics with minor, related topics clustered around them. Keep tweaking, and soon you'll have your chapters, and even the order in which you need to write about them will become apparent (i.e. you have to know how to create a database before you can insert records into one.)

The nice thing about breaking things up this way is that when you're done, you'll have all your topics in small chunks. Breaking your project up into smaller pieces makes it much simpler. Instead of thinking, "how on earth will I ever finish this massive thing," you can focus on the small pieces.

Answer 5

I usually combine what Lauren and Lynn suggest, in that I list every phrase or statement I know about the topic, group them together, and then organize into a rough outline. I have used Scrivner, and Freemind and other mind-mapping tools, but lately, I find myself using Workflowy to do this.

Answer 6

There are some relevant and detailed answers here, to which I can only add my two cents, not a bit more :)

1. Who is your target audience? If it is for beginners - can you go back to your old days of learning programming as a novice, and then try to recollect some things that you loved or hated about some books. It's more likely that the ones you loved are the common selling points that you should stress on, and vice verse. Talk to a few new programmers if you want more inputs on this. If it is a more advanced book, then I suppose it is an easier job for an advanced programmer (which I am assuming you are). You can explain things in the way you would like to know yourself.

2. Most of the programming books are flooded with compiled codes that spoil the learners. If you dare to be a little adventurous, and leave some work for the reader's brain to do. Sometimes those long idiomatic expressions look tiring to brain. Remember Kernighan and Ritchie's?

3. What's the specialty of your book? There are already a bunch of them in market, and you need to be different from them. Surely, different doesn't mean bizarre, but more useful / improved.

4. General tip about writing - start with the structure first. Create the document, write down some bullets that you definitely want to address, and treat it like your own notebook for next few days. Write in plain English, without paying much attention to language. Then go back and revise. You will be surprised to see how many new ideas and improvements emerged out of the same you who was afraid of starting the task a few days back. Happens with me ALL THE TIME.

5. Follow some time management technique - set a daily / weekly limit on time / page that you definitely want to reach. And yes, do get your thoughts discussed, reviewed by peers once in a while. Helps bootstrap new thoughts sometimes.

Hope this helps.

Answer 7

The publisher should have a writing guide. If the book is part of a series, there would be fairly strict formats for organization, language, how to handle code samples, illustrations, tips, quizzes, and many other things. The tone and look and feel of the project should have a lot decided already -- you should not be starting from a blank page. I've worked on programming and software mass-market books, and a lot of things are pre-determined based on the series (i.e., is it a "Python for Dummies" or "Python the Missing Manual" or "Fundamentals of Python" series?)

Rather than a blank page, you should have pages of guidance from the publisher. If not, this is not really a serious project -- very few nonfiction books are written without prior agreement about the subject, format, length, table of contents, number of sample programs, etc.

In a sense, the introduction should be written (understood) in the agreement you make with the acquisitions editor.