I didn’t plan to write a programming book. This means I followed a very inefficient path, which led me to a position where I was forced to re-write the entire content. However, in this process, I have learned a great deal about what I should have done to be more efficient and to deliver more value to my readers. Some of the things I outline in this article are general to any kind of writing, not only technical books, and they also work for shorter pieces such as this one.
Why
If you ever start the path of writing a book, you should ask yourself why you are doing it. There are many reasons, and none is more valid than the other. You could write a book because you want to earn money by selling it. Perhaps a book is an excellent strategy to position yourself in a field. I have seen many people releasing free e-books to collect e-mails for their newsletters, or to try to become known thinkers in an area foreign to them.
Whatever your reason is, the best thing you can do is write it down, so you don’t forget it. The reason you embark on a relatively complex project such as writing a book should guide your decisions. If you know you want to sell your book, you must be sure you meet the market’s needs. If the book is mandatory reading for the students of a class, you should be sure you cover all the needed topics. If you are entering a new field, be sure you are up to date with the area.
The Outcome
Knowing why you write a book only sets the north. The next step is to think about your readers. Think about what message you expect to pass to someone who finishes the book. Depending on the subject and the type of book you want to write, you can think about a list of topics that you should cover. In my case, the book is a guide through an entire project. The outcome for someone who reads the book is a complete program.
I have seen many programming books that tackle different small projects. And with each project, there is a bit of new knowledge transmitted. Sometimes there is cohesion between the chapters, but often they can be read independently. Particularly, books aimed at more advanced programmers tend to be more atomic. Chapters are independent and focus on specific topics, without necessarily building upon each other.
The Base Line
The next crucial thing to know is where the book is starting once you know where the book is going. In my opinion, this may be one of the most challenging tasks. Is your book targeted at people who know how to program, but don’t know a specific language? Or they already know the language but don’t know about programming patterns? Are they comfortable using the command line?
There is always something else that needs to be explained earlier to understand what is coming afterward. It is possible to develop the feeling that your book should include *everything*. When this feeling appears, you should challenge it. Ask yourself the kind of readers you want to have. Are you targeting those who are just starting or those with few years of experience?
Once you fix the baseline and the outcome, you will have an idea of the size of the challenge you are up to. This is the moment to judge whether it is within your reach or better think about something else.
Outline of the Content
Once you know where the book starts and where it should finish, it is time to decide what goes inside. Most books are structured in chapters because they give a clear break to the reader. Once a chapter is finished, they can take a break before jumping to the next. For technical books, chapters should be cohesive and with a narrow scope. Remember that there is no limit to the number of chapters a book can have.
Ideally, if you already know the topic reasonably well, you can write the book’s outline as a series of bullet points. Each element on the list could be a chapter or a section. You can also be slightly more specific and write down some ideas for content, what do you want to transmit, or some keywords.
Sometimes, however, you need to do some research to write the book. Many times, when you decide to write a book, you do it based on what you already know. However, the way you acquired that knowledge may have been very unstructured. Writing a book is an excellent way of challenging that knowledge and filling your own knowledge gaps. If this is your case, the outline of the book becomes fluid.
When your book’s contents become fluid, you should always remember the two anchor points you defined earlier. Those are the only two places to keep you contained, preventing you from going off the rail. Once you start piling content, always check that every step brings you closer to the outcome you expect. If something off-topic appears along the way, store it safely for when you are looking for inspiration for your next book.
Execution
Once you have a project with a clear start, goal, and path, it all comes down to execution. Writing is not only a skill, but it is also a habit. The more you write, the easier it becomes. Writing a bit every day is better than writing a lot once per month. However, you must also acknowledge that writing is something that happens in between other things.
If you manage to spare some specific time per week for your book, it will be a great help. Part of the reasons for losing motivation is the lack of progress. If today your book is not closer to being complete than it was 6 months ago, it is hard to keep the spirits up. If that is the case, first remember why you started writing in the first place. Then, focus again on the outline and think about what is missing.
I, personally, tend to start writing until the point I realize there is something I am doubtful about. I start reading about it, which blocks my writing. While researching, I roam towards topics I didn’t need for clarifying my doubt. What was supposed to be a writing session ends up showing little progress. If you are writing a programming book, the research could be replaced by developing code. Developing while you write is a quick way of diverging from your real goal.
Before starting to write, try to think about the things you need to know. One thing is looking up, another is researching on a subject. When you start writing, just write. Perhaps you make mistakes, maybe some sentences could have been re-written more beautifully. If you keep typing without looking back, you will make significant progress. Remember, progressing is key to keep the motivation.
Once you are done with writing, it is time for editing. Re-read what you have written. Correct what you can, mark the things you are doubtful about, or you are not inspired to improve.
Separating research from the rest is more or less straightforward. It is such a different task that most people won’t really struggle. Separating writing from editing, however, is much harder and takes a lot of discipline. Especially when you see the red marks under the words you type, or the warnings that some text editors generate. Each one should find their own path. Some people prefer to spend time on each paragraph as they write. I prefer writing several paragraphs and going through them on another day.
Planning
If you are one of the lucky ones who can spend a fixed amount of time per week on the book, you can also try to plan for each chapter. If it is your first book, you won’t be able to calculate exact times. You can try, at least, to have clear objectives that you can keep updating as time passes by. You will quickly learn how many words you can write per hour and how many words are there in a chapter. From there, calculating is easier.
If you are not spending a fixed amount of time on the book, you can still plan but without dates. You can always add milestones such as finish researching for the chapters, writing X chapter, or editing. Having a list in front of you that gets shorter after every time you sit to work on something can give you a big motivation push.
Finishing
Obvious as it may seem, finishing the book is an important step. It doesn’t matter how much you correct it. Every time you read what you have written, you will find something to change. Knowing where to put the final dot and deciding that the book is ready takes a lot of courage. Publishing a book entails a degree of risk: what would happen if there is a mistake, or if people don’t like it.
You can always ask feedback from people you trust to gain confidence. The reality is that until you don’t make your book public, there is no way of knowing for sure. Mistakes can be corrected. Especially if you are distributing e-books, improved versions of the text can be shared very quickly with your readers. Especially if you are **writing on a foreign language**, chances of making mistakes that go undetected by automatic checkers are high. However, if the content offsets these issues, readers are still going to be happy.
Finishing a book also includes deciding what the cover will be, the typography, the page size. It can be a lot of fun to tweak these details until it looks exactly as you want. But you should always be practical. Everything is perfectible. It is up to you to decide when the result is satisfactory to make it accessible to others.
Conclusions
Writing a book can be a lot of fun. It can position you in a niche, or it can help you become known in an area outside where you are already known. However, writing a book is not a project that can be tackled without careful thinking. I made the mistake of not thinking ahead of time, writing happened organically. It wasn’t only a mistake, it was also a big one. I had to change the contents while writing, at some point, there were some inconsistencies in the finished book.
For the second version of Python for the Lab, I completely re-wrote the chapters, using what I learned from the first version. I also made a conscious plan and stuck to it. I was delighted with the outcome, to the point of sending it to print so I could actually hold it in my hands.
