A good engineer is defined by their love of taking things apart. Reverse engineering is a fundamental part of this.
Since I’m writing my book without a publisher, and editing with the help and generosity of my friends, I figured I could look at existing technical books to see what works and what doesn’t when it comes to organizing my book’s contents.
Somewhere out there lies a hybrid style that works for me. The question is how much of this I can encode into Asciidoc, either via theming or via extension code.
Ideally, I would rather do this directly in Asciidoc, rather than via a LaTeX or XSL-FO transcoding.
I stopped by the Dussmanns bookstore on Friedrichstrasse this morning to look at the structural features that established publishers use to lend their books a professional finish.
The books I flipped through were:
- Grundkurs C++, by Jürgen Wolf, published by Rheinwerk Computing, I really like the style they used.
- Clean Code, by Robert C. Martin, published by Prentice Hall, I really did not like the style they used. It was appalling.
- Merkmalskonstruktion für Machine Learning, by Alice Zheng and Amanda Casari, this is the classic O’Reilly style. I like half of the style, and I think the other half could use some work.
Things I Liked
First page, clean-sheet repeat of book title — The Prentice Hall and O’Reilly books do this. The Prentice Hall styling is actually not great.
The back of the cover is verso, this page is recto.
Fore-edge markings for each chapter for quick thumbing through and at-a-glance understanding of book structure.
I’ve already partially implemented this where the chapter breaks happen, by using full-bleed PDFs and inserting them into my Asciidoc page flow as images, but I’m not sure there’s an easy way to do this in Asciidoc on a per page basis for an entire chapter; or via postprocessing using PDFBox.
Only one of three books used these markings. I was surprised to see that O’Reilly did not.
Single-line chapter number and name on the verso side + section number and name on the recto side, in the page header.
O’Reilly does this as well in the page footer.
The Rheinwerk Computing book had a chapter + appendix overview, which laid out the 17 chapters + 2 appendices which form the main functional blocks of the book.
This is a great way to give me a quick view into everything. I wish all technical books did this. Pretty sure I can’t do this in Asciidoc.
Also, it is an utterly gorgeous Table of Contents: right-aligned chapter numbers, left-aligned chapter titles, right-aligned page numbers. I think I’ve been staring at formatting for too long, but I can actually appreciate this.
Check this out:
They wait another page or so before inserting the regular, detailed Table of Contents.
Excellent font and spacing control in the Rheinwerk Computing book, with the font-size and margin-top of each header proportional to their level of importance.
The mix of sans-serif versus serif text also creates a clean visual distinction between the headers and content.
I liked the Sidebar box and the table formatting in the Rheinwerk Computing book, too. I like that the border-left and border-right are left out, since it is visually bounded by the page edges anyways.
Everyone uses cocktail napkin drawings, so I am not off the mark in my own work. Also, I like that the formatting always has a border and has padding set around the image.
Things I Disliked
Compare the Rheinwerk Computing book to the Prentice Hall way of styling the Table of Contents, and feel your eyes bleed.
If everything is in bold, what is actually important? It feels like everything is trying to shout from the page. Also, the line-height is too tight.
The figure caption for tables in the O’Reilly books flips from being below for Figures to above for Tables. I’m of two minds about this.
On the one hand, it goes against most styles I’ve ever seen.
On the other hand, it kind of makes sense, as the table caption can provide an ahead-of-time summary of what you’re about to read through.
The Common Structure of Technical Books
Here’s the common structure I saw replicated across multiple technical books:
- Front cover (recto only)
- First inner page, clean-sheet repeat of book title only, as above (blank verso, then recto)
- Second inner page, book title, author, and publisher (blank verso, then recto)
- Copyright page / Impressum (was always verso)
- Dedication page (recto)
- Table of Contents (detailed, always recto)
- Foreword (recto)
- 1..n Chapters
- Chapter first page (with or without illustration; may start on verso or recto side)
- Chapter contents
- Chapter summary (optional wrap-up)
- Chapter bibliography (optional wrap-up)
- 1..n Appendices (recto)
- Appendix first page (with or without illustration; may or may not be forced to recto side)
- Appendix contents
- Index (recto)
- Afterword / Colophon (optional, recto)
It should be possible, by looking at the existing examples, to formulate an effective custom style.
Apropos of Nothing
One thing that totally kills me is the orientation of the text on the book spine:
- In the US, it’s usually rotated 90-degrees clockwise.
- Whereas in Germany, it’s usually rotated 90-degrees counterclockwise.
Hence, when you’re scanning the bookshelves, your brain is constantly rotating spine-text one direction or the other and it kind of hurts.
Featured image: “Cut-away of Berliner acoustic tile”, Emile Berliner collection, 1871-1965 (Source: Library of Congress)