Ask HN: How did you author and typeset your technical book?
10 comments
I use pandoc [0] to convert GitHub style markdown to pdf/epub with some customizations of my own.
I'd probably try templates [1] already available if I needed printable version.
[0] https://learnbyexample.github.io/customizing-pandoc/
[1] https://github.com/Wandmalfarbe/pandoc-latex-template
I'd probably try templates [1] already available if I needed printable version.
[0] https://learnbyexample.github.io/customizing-pandoc/
[1] https://github.com/Wandmalfarbe/pandoc-latex-template
LaTeX with PGF/TikZ gave me higher quality typesetting of text,
mathematics, and technical diagrams than other alternatives I
considered. Learning PGF/TikZ made me suffer, but I wouldn't choose
anything else now, especially for complicated or exact diagrams. For a
build tool I used latexmk. The memoir document class easily handled a
full length book. Wrapping text around images was reasonably effective
with the wrapfig package, albeit slightly buggy. I used the Gimp to
remix public domain clipart just for fun illustrations, and Blender
for some crazy looking 3D cover art. If I were better at Blender I
would have used it more extensively. My workflow was limited to a PDF
target because I couldn't imagine any ebook or web format doing
justice to the math, but it did a nice job of embedding hyperlinks
into the document for things like equation numbers and section numbers
that are usable in PDF readers such as evince. As others have
noted, this advice might not be practical if you're working with a
publisher and have to use whatever boring enterprise software the
publisher demands.
I wrote a book and chose Asciidoctor, because it's got a lot of built-in features for writing technical docs, such as 'admonitions' (the "tip", "warning", "info" blocks, etc.), 'sidebars' (the boxed Q&A/ancillary blocks you often see in technical books) and code syntax highlighting, with per-line 'callouts' (i.e. you can write explanations of what each line in a sample code block is doing). It can also generate images from ASCII diagrams, but I didn't get amazing results, so I created my own diagrams as SVGs in draw.io.
It's easy to render PDF and EPUB, and Asciidoc syntax is not much of a jump from Markdown either. The biggest challenge is learning the correct name of the typesetting feature that you need, so you know what to look for in the Asciidoctor reference. :-)
So my process was as follows:
1. 1 "parent" Asciidoc manuscript, with individual chapters written in separate files and included with "include::"
2. Write sample code, marking each code block with Asciidoctor fencing, and then reference each code block from the manuscript. Asciidoctor will then include the code and add syntax highlighting etc. I also try to write the example code inside unit tests, so it can be tested every time the book is built.
3. Wrap the process in some sort of build tool. I chose Maven (there's an Asciidoctor plugin for Maven). The process builds the book PDF/EPUB, tests the book sample code, and builds any associated artifacts (like an example .zip file).
Now I'm writing a new short book, and this time I'm trying out Pandoc->PDF (via LaTeX). The learning curve is pretty steep, and the LaTeX errors are a bit WTF, but the eisvogel template (as also recommended by asicsp in this thread) is a great way to have something presentable very quickly.
It's easy to render PDF and EPUB, and Asciidoc syntax is not much of a jump from Markdown either. The biggest challenge is learning the correct name of the typesetting feature that you need, so you know what to look for in the Asciidoctor reference. :-)
So my process was as follows:
1. 1 "parent" Asciidoc manuscript, with individual chapters written in separate files and included with "include::"
2. Write sample code, marking each code block with Asciidoctor fencing, and then reference each code block from the manuscript. Asciidoctor will then include the code and add syntax highlighting etc. I also try to write the example code inside unit tests, so it can be tested every time the book is built.
3. Wrap the process in some sort of build tool. I chose Maven (there's an Asciidoctor plugin for Maven). The process builds the book PDF/EPUB, tests the book sample code, and builds any associated artifacts (like an example .zip file).
Now I'm writing a new short book, and this time I'm trying out Pandoc->PDF (via LaTeX). The learning curve is pretty steep, and the LaTeX errors are a bit WTF, but the eisvogel template (as also recommended by asicsp in this thread) is a great way to have something presentable very quickly.
For "Stratospheric - From Zero to Production with Spring Boot and AWS" (https://stratospheric.dev/ ) we used Markua (http://markua.com/ ), Leanpub's Markdown flavour.
We generated the book through Leanpub, so we relied on their typesetting choices entirely.
In terms of the writing process we (three co-authors) used "feature" branches on GitHub and pull requests for each chapter, i.e., once a chapter was considered done, the other two authors reviewed and edited the result.
We generated the book through Leanpub, so we relied on their typesetting choices entirely.
In terms of the writing process we (three co-authors) used "feature" branches on GitHub and pull requests for each chapter, i.e., once a chapter was considered done, the other two authors reviewed and edited the result.
I used https://github.com/SaraVieira/starter-book - works well if you're familiar with GatsbyJS
I have published 2 open source books by using Markdown.
Didn't have a publisher to deal with
Wasted 3months of my time with Apress who really wanted to publish my python book through them and then backed out after 3 months saying "OMG your book is similar to some of our books"
Ans their choice of formatting was strictly Word and they'd even given a word file template and I actually had liked that template!!
On another unrelated note, the pay they were going to give me was low. My Go book earned me much more than they were going to pay me upfront+royalty over 5yrs within 5yrs.
Didn't have a publisher to deal with
Wasted 3months of my time with Apress who really wanted to publish my python book through them and then backed out after 3 months saying "OMG your book is similar to some of our books"
Ans their choice of formatting was strictly Word and they'd even given a word file template and I actually had liked that template!!
On another unrelated note, the pay they were going to give me was low. My Go book earned me much more than they were going to pay me upfront+royalty over 5yrs within 5yrs.
I have a follow-up question. How do you convince publishers to use what you're comfortable with. I tried editing / writing for Apress and I gave up because they wanted me to use MS Word. Not even Libreol Office. I wanted to use vim and RestructuredText with Sphinx.
It's a hard problem.
It's a hard problem.
I published with Apress a few years back. I think the solution is probably that you need to choose a publisher that is already more aligned with the tooling that you want to use.
You have to remember that (by the numbers) the author is a small part of the production process. The reviewers, copy editors, and editors all need to use tooling that they're comfortable with. You're going to have to offer them a powerful incentive to be the special case.
If you want to make your CV (resumé) look spiffy then working with an established publishers is a good idea. Otherwise I think self-publishing is a much better idea; you can proceed at your own pace, you'll reap any financial advantage yourself, and you can use whatever tooling you like. Just be aware that it likely still won't be very remunerative. Oh, and get a good copy editor - after a while it's hard to see mistakes in text you've read many times.
Edit: Also, I thought their Word template was reasonably good, but I would have loved a plaintext format and source control to make it easier to review and compare changes. So I totally get where you're coming from.
Edit 2: And to answer the original poster's question - I think if I was going to self-publish then I would go with a Markdown/Pandoc/LaTeX solution like the one in this Stack Overflow thread: https://tex.stackexchange.com/a/246871
You have to remember that (by the numbers) the author is a small part of the production process. The reviewers, copy editors, and editors all need to use tooling that they're comfortable with. You're going to have to offer them a powerful incentive to be the special case.
If you want to make your CV (resumé) look spiffy then working with an established publishers is a good idea. Otherwise I think self-publishing is a much better idea; you can proceed at your own pace, you'll reap any financial advantage yourself, and you can use whatever tooling you like. Just be aware that it likely still won't be very remunerative. Oh, and get a good copy editor - after a while it's hard to see mistakes in text you've read many times.
Edit: Also, I thought their Word template was reasonably good, but I would have loved a plaintext format and source control to make it easier to review and compare changes. So I totally get where you're coming from.
Edit 2: And to answer the original poster's question - I think if I was going to self-publish then I would go with a Markdown/Pandoc/LaTeX solution like the one in this Stack Overflow thread: https://tex.stackexchange.com/a/246871
Sigh. For "copy editor", read "proof reader" as appropriate. Accidentally making my own point there...
Here’s one approach: https://rkrishnan.org/posts/2016-03-07-how-is-gopl-typeset.h...
A recent post here described a process using Markdown, InDesign, and some custom build scripts:
http://journal.stuffwithstuff.com/2021/07/29/640-pages-in-15-months/
In particular, it introduced some interesting workflows around scripting InDesign that I'd not heard of.
I'm guessing that the typesetting for each book is as unique the book itself! What tools have you found success with? Markdown? AsciiDoc? Microsoft Word? LaTeX? Something else entirely?