It's not a classical open-source project, but what we did with our React.JS koans (and other our OSS repos) was to advertise our React.js book in the README and give a discount code. Essentially, it's an ad for our own book.
The book ad was there almost from the beginning, so we've assumed that the contributors are aware of the way this repo is funded.
As for sponsoring other products/companies - we'd need to see if it's aligned with our goals and with our target group. I don't remember anyone approaching us so far.
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.
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).
(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.
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.
> 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.
I don't recall now just how I originally did the PDF, but it was some CLI tool that read either the markdown or HTML.
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.
That's probably true enough for ebook readers (and I got good results for just epub using my CLI tools) but once I went to InDesign for the PDF layout using it for epub generation was no big deal and that was where I was making final changes to the text.
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.
(If you need the actual markdown files I'd have to see about packing those up. I was writing the book as a Webby-generated site using a combination of Markdown and ERB. I had some scripts that would then use that same generated HTML to package it up as epub. )
It would be great if I could use command-line tools to generate the PDF while not sacrificing the precise look and layout I want but I'm deeply skeptical this can be done without a visual tool and manual adjustments to adjust things for aesthetic reasons. (Or without learning LateX. :))
ok, that didn't take long. can't open your .epub file.
it doesn't validate, and i wonder if anyone can open it.
so that's a major problem that you will need to solve...
unzipped it to find out why, and discovered it was made
with calibre. e-book developers hate that program because
it does a rewrite of the underlying .html and .css files,
creating an unholy mess that's very difficult to decipher.
personally, i won't touch a calibre file; life is too short.
aside from the .epub, the .mobi and the .pdf do just fine
in getting the content across, so even though i would likely
have done them slightly differently, what you have is fine.
still, if you really want more feedback, i can give it. but
the original markdown files would be best, concatenated so
they're just one big file, with the text running linearly.
(a book really works best with the whole thing in one file,
because that usually minimizes editorial inconsistencies
while you're writing, and makes it easier to check later.
it also dampens file-clutter considerably, which is good.)
ok, that didn't take long. can't open your .epub file. it doesn't validate, and i wonder if anyone can open it. so that's a major problem that you will need to solve...
Weird. It was generated using InDesign (though I've now learned that opening the .epub in Calibre's ebook-reader will insert a bookmarks file into the zip).
I then used Kindlegen to turn that epub into mobi for sale on Amazon, and Calibre to create the mobi I offer elsewhere. No one has told me they had any trouble opening files and I've viewed them using assorted programs.
(a book really works best with the whole thing in one file, because that usually minimizes editorial inconsistencies while you're writing, and makes it easier to check later. it also dampens file-clutter considerably, which is good.)
I find it easier to break things out into chapter files. Turning the chapters into a Web site even if only hosted locally) makes it easy to navigate through the whole thing. It works for me.
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!
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?
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.
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.
Thanks for the very interesting article. Sorry if its a sill question but I'm a little bit confused. As someone who is barely starting with node.js, I'm curios if this would be a good architecture for a node.js app, or am I getting this wrong?
Sorry if the question is not clear, I can clarify if necessary :)
I fully agree with the risk that certain ideas will be overused. This leads to unnecessary complexity. I also remember the times of the GoF book and the design patterns rage.
The ideas behind those architectures require time to think through. The sooner you start, the better. Then, slowly, try adopting them. If you have a side project, then apply it over there.
It's crucially important to have a common understanding of the project within a team. The domain knowledge should come from the subject matter experts, but after that it should be a team work to decide which (if any) patterns and architecture should be applied.
Common understanding of the project... yes that is essential. I've got a tangental role on a project right now where that is NOT happening, and predictably the system is a mess. Each developer is being given task assignments by the lead but nobody really understands the overall architecture, goals, and design of the system. I'm actually not sure the lead does either, it's really one of those "make it up as you go" projects. Sadly it'll ultimately be scrapped and have been a waste of time for everyone involved, except to the extent they can learn some lessons from it.
It's a peopleware problem, more than a technical one. If there's no trust in the whole team, then all the design/architecture challenges are less important.
I've just read it today, a good post on this topic:
"We all know Conway’s law: “any piece of software reflects the organisational structure that produced it.”. In the same way, communications patterns between people affects the quality of the software. After 6 months working on a greenfield project I realised I could link all the areas with major technical debt to some unsolved personal conflicts in the team."
It is insane that chess is a worldwide sport/game and still Carlsen only made about $1.2 million USD last year(a lot for me and anyone else I know but for a professional competitor it is quite low). For a sport that a billion people watch you'd think there would be a lot more sponsorships, media attention, etc.
It seems professional eating has more invested in it.
Probably has a bit to do with the fact that Carlsen doesn't care about money, he only cares about chess. There was a tournament recently where he was offered a draw during the match, taking the draw would be a sure way for him to win the tournament and win the 1. place price money. He didn't, he went into an all in fight to win instead (risking his 1. place) - and pulled it off. Also, his father takes cares of his finances so that he doesn't have to deal with it, AFAIK.
That is very honorable. Carlsen is one impressive man. I hope he wins - his attitude and his energy seem to be revitalizing the sport, even here in the States.
Choosing a heavier framework may put you in risk of 'typical', framework-related bugs that often appear. The bugs are not part of the framework, but they are part of the patterns around it.
Discourse 'private topics' leaks (1) are good examples of typical security Rails apps bugs (the result of overusing ActiveRecord). I'm not blaming Discourse, the same kind of bugs appear in other popular Rails codebases (Diaspora, Spree, Redmine).
Ember.js is very Rails-like. I didn't use Ember much, but the patterns look so similar, that it may lead to similar kind of problems as in Rails apps.
I'm not saying that we shouldn't use Rails or Ember. In fact, I'm a big fan of Rails. It's just worth being careful of not falling into the trap of overusing the framework patterns.
The frameworks are best for the infrastructure parts of the app - http, persistence. At the end, it's better that you can control your models. That's the part of Angular that I prefer over Ember - you own your Model part.
Those private topic bugs are not the result of ActiveRecord. We added a group layer on top of existing code and missed some places where queries did not respect it.
Had we used raw SQL instead of an ORM we would have had the same issues. All projects are open to this style of bug. The correct thing to do is report, close them quickly and add tests to prevent them from happening again (which we do.)
"Those private topic bugs are not the result of ActiveRecord. We added a group layer on top of existing code and missed some places where queries did not respect it."
I've seen so many of such bugs in other apps, that I treat them as part of "ActiveRecord price".
ActiveRecord over-usage makes it very easy to miss the places, where queries need to respect new rules.
You're doing an awesome job with Discourse and the team approach to such bugs is very good - no doubts here. Thanks for your work!
Think of the router as the "main" method of your application. It's passing you the initial arguments. You just parse it and run the correct logic and/or display the view that is required.
https://github.com/arkency/reactjs_koans
Thanks to this solution we've had more money to work on this and other OSS projects.