4 ms·

As someone who has just recently started writing programming books [1] I'm really excited to see more such tools! Some thoughts: 1. Code examples are the bigg

As someone who has just recently started writing programming books [1] I'm really excited to see more such tools! Some thoughts: 1. Code examples are the biggest problem to me in the tools that I tried. There's many little things about them, that need to look right - line numbers, display on kindle, line breaks 2. At the beginning, I've used Git and vim for writing in Markdown. However, at some point I realised that I wasn't efficient - I switched to Scrivener [2] and dropped the idea of using Git. In my case, it made me much more productive. 3. Writing an ebook is different than writing code. You probably don't need much of the history. 4. Research is for me the biggest part of writing, experimenting with different ideas, collecting code samples. It's good to have a proper tool to support it. In my case, Scrivener [2] was a huge improvement. 5. I use a combination of Scrivener, Leanpub, Dropbox and getdpd [3] for the whole project. Scrivener for research and notes organisation, Leanpub for generating the result files (PDF, mobi, epub), Dropbox for syncing those two. Getdpd for the selling part. [1] http://rails-refactoring.com/ http://rails-refactoring.com/ [2] http://literatureandlatte.com/scrivener.php http://literatureandlatte.com/scrivener.php [3] http://getdpd.com/ http://getdpd.com/

jamesbritt 13y ago
I also stated off writing a book using Markdown in Vim and was pretty happy at first. One of my goals was to have a Web site that mirrored the book content (http://osc.justthebestparts.com http://osc.justthebestparts.com). (I learned a lot about writing Markdown-to-epub+Web-site tools as well :)) But my book had numerous illustrations and occasionally lengthy code samples. What worked fine on a Web page did not play out so nice in a naive conversion to mobi/epub/PDF. I ended up waiting until all content was basically done and then using InDesign to set the layout (primarily for PDF but it helped with the epub export as well). The biggest issue was making sure that breaks occurred in a sensible way. (I took a look at Scrivener and it just wasn't right for me. But I encourage people to try it out.) I'm all for more tools that make it easier for people to focus on content over the nuts-and-bolts of production but one really needs to be sure that the tools are producing the results you want, and that's going to vary with the type of content.
- bowerbird 13y ago
  pagination and breaks can be problematic in e-books, especially in conjunction with illustrations/captions. but one shouldn't need to move stuff to indesign, as most e-book viewer-apps support css "page-break" now. another good tip is to create small chapters/sections, recognition that screens tend to be smaller than pages. -bowerbird
  - jamesbritt 13y ago
    but one shouldn't need to move stuff to indesign, as most e-book viewer-apps support css "page-break" now. If I were only targeting epub/mobi I wouldn't have bothered with InDesign, but getting the PDF just right was important to me. nother good tip is to create small chapters/sections, recognition that screens tend to be smaller than pages. Since the user can set the font and text size the idea of page size goes pretty much out the window. Using CSS page-break doesn't quite help, since it presumes what has come before and how it fit on the page. What's needed is orphan/widow control and "keep with next" so that, for examples, related sections can be rendered on one page or the next but not split across pages. In practice, though, I found I needed to aim for some sort of highest common factor across popular devices, keep test-viewing the results, and drop anything too clever.
    - bowerbird 13y ago
      jamesbritt said: > getting the PDF just right was important to me. i respect that. how were you generating the .pdf? * > Since the user can set the font and text size > the idea of page size goes pretty much out the window. what pagesize did your .pdf have? that's what i meant. if you put each section on its own e-book screen, and make the sections small enough to fit on one _screen,_ or two, or three, they'll also fit on one/two _pages._ * > Using CSS page-break doesn't quite help, > since it presumes what has come before > and how it fit on the page. i'm not sure i understand. so -- for the sake of others reading this thread -- let me explain further. when you create the e-book, if you segment the book into small-enough sections, it'll generally work, across almost all situations, no matter how the person has configured the fontsize. so there, a "screen-break" comes before each section, and before-and-after images you want to fill a screen. conversely, for the .pdf, you _know_ the pagesize, and the fontsize as well, so you know where pagebreaks are, and you add/delete/change until you get what you want. * > What's needed is orphan/widow control > and "keep with next" so that, for examples, > related sections can be rendered on one page > or the next but not split across pages. it would be nice if the programs had enough smarts to do this automatically; until then, you do it manually. but you don't need indesign to do it; you really don't. i'd be happy to show you how i'd do your book, if you'd be interested in seeing it, if you send me a copy of it. * > In practice, though, I found I needed to > aim for some sort of highest common factor > across popular devices, keep test-viewing > the results, and drop anything too clever. that is the approach that is needed these days, yes. -bowerbird
csdreamer7 13y ago
How does selling on your own site compare to selling on Leanpub and KDP?
- andrzejkrzywda 13y ago
  I didn't consider and test KDP, so I can't say anything. As for Leanpub: 1. Last time I checked, they didn't let me take the customer emails and use outside of Leanpub. I find it a very important limitation to the way I do the marketing - via my mailing list. In practice, my readers are more Leanpub customers, not mine. I want to build long-term relationship with my readers, to deliver more value to them, even after they bought my book. To be fair - Leanpub has their own tool for sending emails, I haven't tried that. I'm happy enough with MailChimp, not to see reasons to switch. 2. From the tools I researched, Leanpub is the best when it comes to PDF/mobi/epub generation. It takes a while to learn their process but it was worth it. 3. I'm really grateful that Leanpub allows the process I'm doing - generate the files using their tools, but selling on another site. Overall, the tools you're choosing should fit your whole process of researching, writing, marketing, selling.
acoleman616 13y ago
I also started off on a very similar path writing my programming book [1] and ended up switching over to using LaTeX-powered Texpad for Mac. It's resulted in a huge gain in productivity, in terms of both managing the content and the code samples and keeping everything nice and consistent. (That last item can become difficult, much quicker than I originally anticipated.) It's wonderful to see more tools cropping up in this area; there's most definitely a need for them! [1] http://www.alexpcoleman.com/your-first-web-app/ http://www.alexpcoleman.com/your-first-web-app/
JunkDNA 13y ago
I'm working on a book right now and I struggle with the syntax highlighting part with Scrivener. Overall, I really like Scrivener, but it seems really hard to integrate proper syntax highlighting and code formatting in an efficient manner.
otherdave 13y ago
Do you write it in Scrivener too? Or just use it as a notebook and then write it up in another text editor?
ilamont 13y ago
My company just published our first programming book, jQuery Plugin Development In 30 Minutes. I worked with the author to establish a workflow that leveraged GitHub and markdown, but at the end of the day the material had to be brought into Scrivener for the final production steps. FWIW, Scrivener has limited markdown support that let me bring in the code blocks and terms that are formatted in the Scrivener editing window. But getting text formatted as code to compile properly to various versions (PDF, epub, mobi, etc.) took some work -- specfically I had to freeze the formatting for every block and term. It was a pain, but the final product turned out well. The only other thing I would like to add is I wish there were a way to get the Scrivener manuscript back into markdown and Git, for future revisions. Anyone have ideas on how to handle that?

jamesbritt 13y ago

I also stated off writing a book using Markdown in Vim and was pretty happy at first. One of my goals was to have a Web site that mirrored the book content (http://osc.justthebestparts.com http://osc.justthebestparts.com). (I learned a lot about writing Markdown-to-epub+Web-site tools as well :)) But my book had numerous illustrations and occasionally lengthy code samples. What worked fine on a Web page did not play out so nice in a naive conversion to mobi/epub/PDF. I ended up waiting until all content was basically done and then using InDesign to set the layout (primarily for PDF but it helped with the epub export as well). The biggest issue was making sure that breaks occurred in a sensible way. (I took a look at Scrivener and it just wasn't right for me. But I encourage people to try it out.) I'm all for more tools that make it easier for people to focus on content over the nuts-and-bolts of production but one really needs to be sure that the tools are producing the results you want, and that's going to vary with the type of content.

bowerbird 13y ago
pagination and breaks can be problematic in e-books, especially in conjunction with illustrations/captions. but one shouldn't need to move stuff to indesign, as most e-book viewer-apps support css "page-break" now. another good tip is to create small chapters/sections, recognition that screens tend to be smaller than pages. -bowerbird
- jamesbritt 13y ago
  but one shouldn't need to move stuff to indesign, as most e-book viewer-apps support css "page-break" now. If I were only targeting epub/mobi I wouldn't have bothered with InDesign, but getting the PDF just right was important to me. nother good tip is to create small chapters/sections, recognition that screens tend to be smaller than pages. Since the user can set the font and text size the idea of page size goes pretty much out the window. Using CSS page-break doesn't quite help, since it presumes what has come before and how it fit on the page. What's needed is orphan/widow control and "keep with next" so that, for examples, related sections can be rendered on one page or the next but not split across pages. In practice, though, I found I needed to aim for some sort of highest common factor across popular devices, keep test-viewing the results, and drop anything too clever.
  - bowerbird 13y ago
    jamesbritt said: > getting the PDF just right was important to me. i respect that. how were you generating the .pdf? * > Since the user can set the font and text size > the idea of page size goes pretty much out the window. what pagesize did your .pdf have? that's what i meant. if you put each section on its own e-book screen, and make the sections small enough to fit on one _screen,_ or two, or three, they'll also fit on one/two _pages._ * > Using CSS page-break doesn't quite help, > since it presumes what has come before > and how it fit on the page. i'm not sure i understand. so -- for the sake of others reading this thread -- let me explain further. when you create the e-book, if you segment the book into small-enough sections, it'll generally work, across almost all situations, no matter how the person has configured the fontsize. so there, a "screen-break" comes before each section, and before-and-after images you want to fill a screen. conversely, for the .pdf, you _know_ the pagesize, and the fontsize as well, so you know where pagebreaks are, and you add/delete/change until you get what you want. * > What's needed is orphan/widow control > and "keep with next" so that, for examples, > related sections can be rendered on one page > or the next but not split across pages. it would be nice if the programs had enough smarts to do this automatically; until then, you do it manually. but you don't need indesign to do it; you really don't. i'd be happy to show you how i'd do your book, if you'd be interested in seeing it, if you send me a copy of it. * > In practice, though, I found I needed to > aim for some sort of highest common factor > across popular devices, keep test-viewing > the results, and drop anything too clever. that is the approach that is needed these days, yes. -bowerbird

csdreamer7 13y ago

How does selling on your own site compare to selling on Leanpub and KDP?

andrzejkrzywda 13y ago
I didn't consider and test KDP, so I can't say anything. As for Leanpub: 1. Last time I checked, they didn't let me take the customer emails and use outside of Leanpub. I find it a very important limitation to the way I do the marketing - via my mailing list. In practice, my readers are more Leanpub customers, not mine. I want to build long-term relationship with my readers, to deliver more value to them, even after they bought my book. To be fair - Leanpub has their own tool for sending emails, I haven't tried that. I'm happy enough with MailChimp, not to see reasons to switch. 2. From the tools I researched, Leanpub is the best when it comes to PDF/mobi/epub generation. It takes a while to learn their process but it was worth it. 3. I'm really grateful that Leanpub allows the process I'm doing - generate the files using their tools, but selling on another site. Overall, the tools you're choosing should fit your whole process of researching, writing, marketing, selling.

acoleman616 13y ago

I also started off on a very similar path writing my programming book [1] and ended up switching over to using LaTeX-powered Texpad for Mac. It's resulted in a huge gain in productivity, in terms of both managing the content and the code samples and keeping everything nice and consistent. (That last item can become difficult, much quicker than I originally anticipated.) It's wonderful to see more tools cropping up in this area; there's most definitely a need for them! [1] http://www.alexpcoleman.com/your-first-web-app/ http://www.alexpcoleman.com/your-first-web-app/

JunkDNA 13y ago

I'm working on a book right now and I struggle with the syntax highlighting part with Scrivener. Overall, I really like Scrivener, but it seems really hard to integrate proper syntax highlighting and code formatting in an efficient manner.

otherdave 13y ago

Do you write it in Scrivener too? Or just use it as a notebook and then write it up in another text editor?

ilamont 13y ago

My company just published our first programming book, jQuery Plugin Development In 30 Minutes. I worked with the author to establish a workflow that leveraged GitHub and markdown, but at the end of the day the material had to be brought into Scrivener for the final production steps. FWIW, Scrivener has limited markdown support that let me bring in the code blocks and terms that are formatted in the Scrivener editing window. But getting text formatted as code to compile properly to various versions (PDF, epub, mobi, etc.) took some work -- specfically I had to freeze the formatting for every block and term. It was a pain, but the final product turned out well. The only other thing I would like to add is I wish there were a way to get the Scrivener manuscript back into markdown and Git, for future revisions. Anyone have ideas on how to handle that?