Some of you have published technical courses or books that contain code snippets and inline code (class names, method signatures, etc.). I currently use Scrivener for this purpose, but its support for code is not ideal. I was therefore wondering what other tools make this easier. iBooks Author is another option I’m aware of, but I haven’t used it much yet.
I write in Markdown. Ulysses is a pretty nice editor for Markdown. I publish to MOBI, PDF and EPUB via pandoc, kindlegen and Prince.
I have a talk about this stuff, some resources and links to slides can be found here http://rachelandrew.co.uk/presentations/css-books
1 Like
Thank you for the tips, Rachel. It’d be great if I can write everything in Markdown and your tips are a great starting point for this.
For my own API documentation (so not directly applicable to books, but another point of reference) I use a mix of Markdown (slightly customised for my needs) for general “discussion” text and XML for structured information - example file. That way it is fairly trivial for me to generate HTML documentation pages - example file rendered.
That way I can continue to live in my beloved text editor 
.
XML might not be “hot stuff” in the tech world anymore, but it does have some good uses, and its working well for me there so far!
Allan
1 Like
I find that using markdown is far too limiting for the kind of things I write (mostly help files for my users). As @allan_jardine demonstrates having the power of XML allows for a far richer output which can help the user stay oriented and engaged. Being able to style certain phrases or keywords in meaningful ways can accelerate the reader’s understanding of things. Having “tip” blocks “warning” blocks, or asides like they do in programming books is nice too.
Unfortunately writing straight-up XML isn’t much fun. For that reason I am currently scratching my own itch by creating a rich content editor.
@allan_jardine I understand that Markdown may be too limiting for certain use cases, but I’m prepared to make some compromises. Markdown’s portability and ubiquity is a major plus in my opinion.
@Oliver Is that something you plan on selling or is it for personal use only?
@bartjacobs the plan is to sell it as a product. I hope to have a private sneak peek/beta version available soon. If you’re interested PM me here. Also, I’d be interested in hearing more about your use case. Cheers!
@Oliver That sounds good. What platform are you targeting? My use case is fairly straightforward, that is, technical writing.
If you want to go really heavy duty, DocBook is pretty good in a lot of ways, as it comes with an entire toolchain that you can use to mangl…process your documentation.
It is very heavy duty, though, with a steep learning curve. I’m not sure it’s ideal for an agile/MVP/bootstrapped kind of thing unless you really know what you’re doing.
@davidw DocBook looks a bit overkill for my use case. I’d like to stick with Markdown if it meets my needs.
It’s a downloadable product so I am targeting Windows and Mac. I could possibly target Linux in the future if demand is high enough.
I used LeanPub for my book.
They take your Markdown and automatically created pdf, epub and mobi files.
I use Scrivener for my fiction, but like you, found it not so great for programming. All the other tools I tried weren’t that great either. Leanpub takes a bit of getting used to, but they create great books once you understand how they work.
That’s certainly an option and I like the fact that I can use Markdown. The downside, however, is that you’re tied to a specific publisher. My plan is to team up with Gumroad.
No, you are not. I sell that book on Gumroad as well. Leanpub are not publishers, just distributors. Big difference. That means that, unlike traditional publishers, you retain full ownership of copyright.
With Leanpub, you don’t even have to publish with them. When I first started out, I used LeanPub to write the book, but then sold it via Gumroad. Only later on, when a few people asked, I published it on LeanPub as well.
LeanPub is quite good in that way- there is no need to use their publishing service. But I do it anyway, as I have had a few hundred dollars of sales from them, all without doing anything.
The only thing I hate about them is they take 45 days to pay you, while with Gumroad you get it within days/weeks. (Yes, I know why, but still. They could handle refunds the way everyone else does.)
I used Sphinx for my books. It’s not perfect, but it works really well with code snippets.
I wrote a little bit about it here:
Thanks for the tip, Pedro. I’ll definitely take a look at Sphinx.
Help and Manual used to be my weapon on choice, though I rarely get asked to write manuals now (and would refuse if asked!)
APC