There are no comments yet...Kick things off by filling out the form below.
The Importance of Styles in Programming Books
Probably you know that Bill Bridges is the Development Editor of my upcoming Professional Visual Studio Extensibility book. He has done invaluable work on the book and has helped me during the writing process a lot. Thank you, Bill!
In his recent blog post, he has pointed out to something that was the topic of our internal conversations during the writing process and that is about styles in programming books. He has spent a lot of time on redoing some formatting in my book to keep the consistency and choose the best style.
All publishers have a defined templates as well as a set of guidelines on how to format their book series based on their print properties and readability of the book. All of these guidelines are easy to apply for all programming book texts except one and that is where you want to choose the style for some programming terms. You can choose headings, bullet or numbered lists, source code listing or bold face text where appropriate but where and when to use one of styles for programming terms in normal text?
Wiley has a Code in Text style for Wrox books (that we simply call it CIT) and this style is appropriate to differentiate the programming terms (along some other kinds of texts) from normal text. There is also a list of places that you can use this style as well as some guides on where to use or not use it.
Even though the usage of this style is demonstrated clearly but still editors are who should decide on them for their books. As Bill says, the most important thing is choosing a constant formatting for whole the book not depending on the guidelines.
Since programming terms are wide and are growing every day, there are many open points to ask about usage of such formatting. For example, for some terms like class and property names, it's explicitly recommended to use CIT formatting but how about XML elements and attributes? This was a concern for us for some chapters of my book. Bill liked to have all terms capitalized in normal text but I wanted to use CIT style for them. Finally we ended up with a good formatting strategy that I inspired from Bill Evjen's titles.
The best way to handle such situations is having a discussion with editors to choose the best formatting both from a developer and publisher point of views and we did this and fortunately could solve our problems easily. Of course, we had a look at other titles and how they had handled such situations and the quality of the result to get the benefit of their experiences for our book.
But Bill has a very special idea about the CIT formatting and he says that it's better to keep the usage of CIT style as less as possible and it's important to only have a consistency for the book.
I would disagree with him to some extent for some reasons. Like many of you, I've read lots of technical programming books from all well-known publishers and various authors and editorial teams and have found pros and cons of different formatting strategies.
The necessity of having a different style for programming terms in normal text is something obvious because many of the programming terms and names are similar to real world terms and words and for some cases they're common English words that frequently appear in any text. If we don't choose a different style for such terms then they may get confusing for readers. Reader, even a technical reader, may have no background in a field to know if the used term is a normal text or a programming term so we should let him or her know about this.
For a non-technical person it seems better to choose a text with less formatted words because she prefers simplicity than complexity. But when it comes to technical world, we need to avoid any confusion for readers. Look at the following text and consider that you know this text is talking about some XML stuff before reading the text:
You see that name is the direct child of the person but its position doesn't matter at all.
And compare it with this text:
You see that name is the direct child of the person but its position doesn't matter at all.
Don't you think the first text can be confusing for the reader? Even if it's not confusing but it can take some time from the reader to understand the actual meaning of it and can move his focus from the main topic to something completely unrelated!
As you see, things may get more sensitive when you're dealing with case-sensitive programming terms like XML elements and attributes and here it's very critical to use styles.
Even though I agree with Bill that in some cases we can remove styles from texts and make our texts simpler without affecting the readability for readers but I don't agree with him for some cases where he prefers to keep texts in normal form.
Styles are very important in a programming book and styles for programming terms that appear in the normal text are the most important style in these technical books. There is no doubt that we (as developers) expect such formatting when reading a programming book.
[advertisement] Axosoft OnTime 2008 is four developer tools in one: bug tracking, project wiki, feature management, and help desk. It manages your development process so developers can focus on coding. Installed or Hosted – Free Single-user license -- Free 30-day team trial.
No Comments : 10.31.07