Skip to content

Self-publishing a book, Part 3: Editing and Reviewing

October 29, 2012

Part 1: Why and How
Part 2: My tool chain

When you use a major publisher, you’ll get an editor that is responsible for making the book a good book. But when self-publishing, the one responsible for the outcome is you. There are several areas of responsibility that normally fall on the editor even if the editor doesn’t do it him/herself.

Kicking the author

Making sure the book gets done is the major role that typically falls to the editor. Without it the other roles become pretty pointless.

Spell/grammar checking

Making sure the language is spelled correctly and uses good grammar helps avoid the readers getting hung up on small errors. This means your editor should be a native speaker of the language you are writing the book in. Preferably the editor should have some education in writing or English, and can help not only to get rid of grammatical errors, but suggest alternative ways of writing it to increase the flow and make the book more easily read. This is even more important for a technical book, as technical writers tend to not be very good at this sort of thing.


A book of fiction needs to be understandable and gripping, and a technical book needs to have the chapters in an order that means that you don’t have to jump forward in the book to understand it. Technical books are rarely read from start to finish, but if something is hard to understand, the explanation should not come later, unless you specifically add a “See chapter X” for that.

Technical books also need to be checked for technical errors. All this is done by reviewing, just like spelling and grammar checking is. But it doesn’t need to be done by people who speak the language. It should instead be done by people in the target audience, and for technical books also preferably some person who is highly knowledgeable in the topic.


The design of the book is up to the publisher when you have one. Usually the editor will find a cover designer. For your book, you can either design a cover yourself (it’s hard) or use finished cheap designs online, or more expensively hire somebody.

What I did

If you are self-motivated and like writing the book, you may not need somebody to kick you to work on it. On the other hand, it can be good to have a second set of eyes to tell you to stop working on it and publish it already. If you feel uncertain here, engage a friend in this role. Somebody that can be relied on to read the drafts and tell you what works and what doesn’t, and makes sure you stop when the book is ready, and kicks you if you aren’t working on it.

I had Brandon Rhodes as an editor for the first chapters, and other than that I used writing the book as an excuse to procrastinate less interesting work. It’s not an ideal situation, but I did get the book done, so I guess that was good enough. Thanks again Brandon!

I also lined up a couple of reviewers. Some for checking my non-native English, and some to check the technical contents. Here I have a small warning to do: The people supposed to do technical reviewing will end up mostly giving you a list of spelling and grammar errors, even though you tell them that this is not what they are supposed to check. This will usually mean that the technical content is good enough, although in some cases people will just get hung up on the spelling errors to the point where they don’t have any technical feedback to give, because the spelling mistakes annoyed them so much they didn’t even think abut the content.

I ended up having three technical reviewers of the “target audience” type, in my case Python developers with little or no Python 3 experience. I got some useful technical feedback, and a lot of spelling errors fixed. Thanks again, Godefroid Chapelle, Jasper Spaans and Wyn Williams.

I also had one “expert” technical reviewer, Martin von Löwis, who had already done a lot of Porting to Python 3, and is one of the core developers of Python. He was able to point out some big and very non-obvious problems in the examples I had, and having that sort of feedback really helps putting confidence in that what you are doing is not far off the mark. Thanks Martin!

I also had another reviewer in the chain, Alice Bevan-McGregor, who was supposed to do mostly spelling and grammar checking. Unfortunately Alice ran out of time and only finished a couple of chapters, but did an amazing job on those chapters, coming up with rephrasing of my English that improved the language immensely. This opened my eyes to that I should really have had a proper editor. Thanks Alice!

I designed the book myself. As a result it looks like shit. But it’s a technical book for a niche audience, so that’s not really a big issue. The cover picture is great, though. I found that by searching for Creative Commons pictures on Flickr, and I found a picture by Emmanuel “Tambako” Keller. It was Creative Commons so I could have used it without permission, but I asked anyway to make sure. Thanks! On the inside of the book I used standard LaTeX templates for the design and layout, mainly changing fonts and some margins.

What you should do

I really recommend you to find editors to match your weaknesses. This can be hard without a lot of self-insight. If you write a technical book in English, find somebody who knows English well, and has a flair for writing. Be prepared to pay that person. Writing a book is a lot of work, but so is editing it.

Technical reviewers are easier to find. Reading through the book to make sure it’s understandable is not that much work. When you are involved with a community like the Python community a lot of people are prepared to help out. I’ve reviewed several books myself for Packt Publishing, receiving only a copy of the book as payment, and I do it to help the people writing the books, whom I know through the community. If you are writing a technical book, you are probably using a source control system, and then you can in fact just give the reviewers access to the repository and fix mistakes directly.

Unless you know you are a good designer, having a professional designer make the cover can also be helpful. Many self-publishing services can help you with this. They also typically have templates for the insides of the book that will look good.

At the end of this, you should have ended up with a book that is as good as can be expected. If you have a good editor, several technical reviewers and use a professional cover designer there is no reason the book would be significantly worse than a book by a publishing company.

A final fourth part of this series will come in the future, where I talk about what happened after publishing the book, sales and payments, and creative commons etc.


From → book, plone, python, python3

  1. Nippey permalink

    Hey Lennart,

    today I stumbled over your online-book, on my way to find out about the pitfalls of writing code that works in python2 and python3.

    I had to fight with os.path.walk vs os.walk, maybe this is interesting enough to add it to a later revision of your book.
    It seems there is no ‘golden’ solution that applies to all use cases, but pointing out some possibilities will surely help the python beginners out there (including me of course ;] )

    Thank you for the book!


    PS, my personal solution was:

    if sys.version < '3':
    os.path.walk(self.path, self.func, self.args)
    for root, dirs, files in os.walk(self.path):
    self.func(self.args, root, dirs+files)

Trackbacks & Pingbacks

  1. Self-publishing a book, Part 2: My tool chain « Lennart Regebro: Python, Plone, Web

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: