This one is for authors and writers. Those who teach us how to use our tools and code in new programming languages. They ought to know what we think about their writings. Are you writing for programmers? Good. Stephen King once wrote his formula for good writing as: Read a lot. Write a lot[1]. Consider this a small contribution to your own Read a lot.
About six seasons ago, I got caught up in Brian Kernighan's heaven. All his books are well written, inspirational, and instructive. And I know. I picked Software Tools in Pascal and it taught me about filters (think AWK), pattern matching (think GREP), version control (just think about your favorite one)[2], and even archiving. It taught me all this, but it did not teach me Pascal. I heard Pascal being in the title scared off many a programmer and this is absurd.
I could not believe my eyes when professor Kernighan replied to the email I had sent him afterwards, considering the question. I was asking how he managed to write such amazing books. In other words: share your secrets. He even gave me the okay, two days ago, for using his advice in this article. We should be glad to have professor Kernighan among us, both authors and programmers.
Write what you care about instead of what is hot. We start with this big issue of our field. No, I guess I am wrong. The Da Vinci Code had many clones that gathered a lot of dust on the shelves. But when it comes to computer programming, the problem is increased several manifolds.
Let us take a look at that online bookstore over there. Cloud Computing seems hot. Did these authors really care about that topic? No, they seem to be pouring this buzz word and books down on us. No wonder the whole thing is still cloudy. Many did not care about the topic, us, and our time. We will always tell, and we will not get their books. And if we do get them, we will leave them to dust after a short time. So once again: write what you care about instead of what is hot.
Ideally, you want to be an authority or expert on the subject. Books in our field are not fictions. The programs we write are used by real people in the real world. If the author fails, the programmer and thus the program will also fail. There is not a single subject in programming that you would not find online nowadays. So if you don't know a lot about the subject but always get the words right, please go ahead, research and write for us.
Examples. We just can't beg enough for them. I like reading one-stars and two-stars reviews on Amazon, for fun. For programming books, there is a repetitive theme: the examples provided are not working. In many cases, you know a programmer wrote the review. He or she took great pains to test the code, got frustrated and gave a bad rating to otherwise a good book. Sometimes it's okay, we forgive and get the book. But other times it's the deal breaker.
In addition to being well written and tested, examples have to be useful. In his reply to me, professor Kernighan has written:
I like real code illustrating real situations or problems that working programmers are likely to face and thus profit from. I get unhappy with made-up artificial examples, and with code that clearly does not work.
Did you learn Object Oriented Programming from books? Me too. Remember the Car class with a method that tested if a Car instance has four wheels? Or that Shape class that tested if a shape has 4 sides? Better (or worse): a Cow class, subclass of the Animal class, with a method that made a Cow instance moo. If you have seen these before, do not raise your hand. You will never see them in real life coding situations.
I could be taken wrong on that previous paragraph. For my defense, yes I did get the concepts. I am only complaining about not using them in any coding situation.
Better examples should make use of the Web for instance, or anything that the programmer can profit from nowadays. What if instead Shapes and Cars, we have Requests? Instead of hasFourSide() and moo(), we have getURL()? SecuredRequests would subclass Requests, for example.
I admit, it is not going to be easy. But I believe the readers will get it. They will, because these are terms and notions they encounter everyday. Our web browsers speak that very language to us. Even today, Chrome told me that the URL I requested was not found on the server. And what's more, these are useful skills in the making. In professor Kernighan's words:
Pick examples that are realistic and representative, that illustrate things that your readers are likely to want to do. Make sure they are correct. As a reviewer, I worry about a manuscript where the examples are wrong; as a reader, I can't trust anything in a book where the examples contain errors.
I prefer smaller books and I am not alone. This is by no means a rule. Python Essential Reference, for instance, is my favorite Python book. Just about 600-pages long without the ToC and the index. The language is covered in Part 1; about 190 pages. Part 2 is a review of the most useful modules with examples written by the author! He did not just copypasta from the documentations. Part 3 covers extending and embedding Python. I commend David Beazley for the effort.
So, you see, long books are not always bad. In any case, long books are great when they act as reference with examples crafted by the author. This is what people liked about Richard Stevens' books, however long they are.
What size then? Between 150 and 250 pages not including the T.o.C. and the index pages. These numbers are based on many good books: Software Tools in Pascal, The C Programming Language, Practical Django Projects, JavaScript: The Good Parts, etc...
Here's what professor Kernighan has to say about how the writing should be:
Try to place yourself in the shoes of someone who doesn't know a lot about the topic, and who knows the basics but isn't a language lawyer or a super programmer, and try to lead then by the hand through what they need to know.
Jargon becomes a big problem when the author knows too much. At some point, the author forgets that the purpose of the book is to teach, and it should not be a display of knowledge.
I commend professor Parr for his great book, Language Implementation Patterns. The clarity and the didactic style made me fall in love with it. Many complained about him using his tools ANTLR and StringTemplate. Folks, when I was reading the book, I barely knew Java but I translated most of the examples to pure Python because the notions were well explained. Professor Parr worked hard on the explanations and the order in which the notions are presented is really coherent. That's how it ought to be.
One last thing about content. We have too many practices and paradigms going around, and books that are less philosophical and evangelistic about them are what we need. We also get tired, you know. Remember how the old engineering proverb goes, The good thing about standards is that there are so many to choose from. The time-pressured programmer will always go with the appropriate paradigm when the situation calls for it.
Writing is difficult. It is. That's why good writers surround themselves with people who can provide good criticisms about their work. Professor Kernighan writes, I used Doug McIlroy and Rob Pike. Stephen King has Tabitha, his wife, who gets stern sometimes and tells the great author when a passage is boring her. Great critics should be authors' best friends.
On when to start, professor Kernighan writes:
Try to get it done sooner rather than later. It's already more work and will take longer than you think, so concentrate on getting it finished. That will also help keep it to a reasonable size and probably help to keep it current.
Ah, poor books, outdated by the very technology they cover before they even get printed! At this point, authors should stop and think about how fast the programming field moves, and take the previous piece of advice to heart.
Well, another article on writing is about to end, and I guess everyone knows what's coming next. Right? The Elements of Style. Get it and read it often. It is not pure chance that a book that is more than 50 years old is still recommended by great writers today.
Godspeed to all authors out there.
Thank you professor Kernighan for replying to my email, and then agreeing that I use it for this article. Writing this article, was like having you behind my back. You have been my inspiration for years.
Thank you Steven for reviewing my article.
[1] : Taken from, you probably know it by now, On Writing.
[2] : We sometimes get tired of discussing preferences.