splitting Chapter 2 into smaller chapters

[jtnimoy]

ok, I took a look at the PDF and I think my chapter will breakdown into 5 smaller chapters. I'm going to try and call them "Intro to C++ part 1", "Intro to C++ Part 2", etc. I hope that is acceptable, realizing we're trying to keep it at group effort. If I'm lucky, I'll be able to nickname each of the 5 parts.

The alternative is to write a succinct little advertisement for the real book references, and that doesn't warrant even a single chapter.

[bilderbuchi]

I think neither is very attractive (although I fail to see what's wrong with succinctness ;-) ). Especially, if we just name the chapters part I-V, we might as well not bother splitting them up. Can't you find bigger thematic blocks you can use to structure the chapters? Maybe by consulting those real book references and see how they have done it?

[bilderbuchi]

Also, dividing into meaningful subdivision potentially leads to a better structure of your text, and probably identifies areas where the content can be honed down a bit?

[jtnimoy]

I doubt that major reduction will happen - at most, 50% (of the warmth and character) could be cut off, and that still leaves us with a handful of chapters. Is it more important that ofBook have a complete C++ intro, or more important that each author stay within their page count? Perhaps I should sign each chapter with a different nom-de plume ;p

[mikewesthad]

I would say that it isn't a binary choice between those two options. It seems to me that the goal of the C++ chapter should be to equip new coders with the ability handle most of the syntax and concepts that they will be encountering in the following chapters and then to empower them with the knowledge and confidence to know what to do when they encounter unfamiliar syntax and concepts. If you want semi-fresh eyes to take a look at the chapter and suggest possible ways to reduce it without losing your voice, I'm happy to take a look.

I might be misattributing this, but I think @ofZach brought up the possibility of having an abridged version and an unabridged version.

[bilderbuchi]

If one of our chapters clocks in at 100+ pages (or about one fourth of the book), we have to ask ourselves if there is an imbalance, warmth and character or not. Are we writing a book about (intro to) C++, or a book about OF? Are we still effective in conveying what we want (OF is great) if the C++ intro fills a quarter of the book? Should we then maybe defer some of that knowledge to more in-depth literature (which is widely available, there are huge numbers of C++ books out there), and concentrate on our message? If you can condense the chapter by 50% I'd say go for it, that's more than 50 pages saved, right there - that's two "normal" chapters! Also, take a look at how you can streamline some of your ascii art graphics, the while loop pyramid takes two pages, the bouncing ball 7+(!), two pages for a stream of numbers that could also be printed horizontally, one page of random chars, where 15 lines would do for demo purposes, etc..

We also suffer from nonexistent downscaling in the pdf output, I'll try to make latex understand the width given in image embeds (if any), so we can get smaller/scaled figures.

Page count per author/chapter is not an ironclad thing, but without it the book will grow out of bounds! We're already at 400+ pages, and not even all chapters are begun/finished. If the book is too large, nobody's gonna bother reading it (or print it, for that matter!) When did you last read completely through a 600+ pages technical tome that was not a reference book?

[ofZach]

I think we can do anything online, where it's possible people will link to chapters or read as they like, etc, but in a printed or distributed book (pdf, print on demand, etc) I think we should use an abridged version of this chapter to be fair to other authors, who are trying to do a slice of a topic and to make things easier on the reader, keep things small enough and navigable. I think in general authors shouldn't be afraid to append a "for deeper investigation" see (x) to their chapters, there's often times only so much you can do -- many of these chapters should be books -- an in your case, it could very well be, check out further chapters in my intro to c++ here.

In that way, I think abridged vs unabridged makes sense... what do you think @jtnimoy ?

[jtnimoy]

i'm trying to imagine what the abridged 30 page version would be like.

On Wed, Mar 19, 2014 at 2:32 PM, ofZach notifications@github.com wrote:

I think we can do anything online, where it's possible people will link to chapters or read as they like, etc, but in a printed or distributed book (pdf, print on demand, etc) I think we should use an abridged version of this chapter to be fair to other authors, who are trying to do a slice of a topic and to make things easier on the reader, keep things small enough and navigable. I think in general authors shouldn't be afraid to append a "for deeper investigation" see (x) to their chapters, there's often times only so much you can do -- many of these chapters should be books -- an in your case, it could very well be, check out further chapters in my intro to c++ here.

In that way, I think abridged vs unabridged makes sense... what do you think @jtnimoy https://github.com/jtnimoy ?

Reply to this email directly or view it on GitHubhttps://github.com/openframeworks/ofBook/issues/40#issuecomment-38109684 .

[mikewesthad]

So here are some quick, unsolicited suggestions for an abridged version from just skimming through the pdf:

As @kaylalewis mentioned, the history section feels a little jarring. That section could be excluded. 5 pages saved.

The section on random functions can be shortened to on example (with the other left as an exercise for the reader). 3 pages saved.

Excursion into using the distance function in the "For-Loop" section can be left as an exercise for the reader. 2 pages saved.

The section on creating your own replacement algorithm for the random function can be omitted (or again, left as an exercise). 4 pages saved.

The whole bouncing ball section could be omitted. 17 pages saved.

Plus the savings that @bilderbuchi suggested from tightening up your print-outs and resizing images. This will depend on whether you try any of the above mentioned omissions. I could see you saving a lot of pages this way. 10 pages saved?

That's a potential >40 pages saved without talking about ways to tighten up explanations.

[jtnimoy]

YES! Many thanks. All these details add up to a big reduction.

I'm learning Dart language right now in a fleeting attempt to participate in devart, and I'm seeing how they breeze past a lot of the fundamentals and put "we assume you have prior programming experience" in the beginning.

https://www.dartlang.org/codelabs/darrrt/

perhaps that's another mistake I made.

J

On Wed, Mar 19, 2014 at 6:37 PM, Michael Hadley notifications@github.comwrote:

So here are some quick, unsolicited suggestions for an abridged version from just skimming through the pdf:

As @kaylalewis https://github.com/kaylalewis mentioned, the history section feels a little jarring. That section could be excluded. 5 pages saved.

The section on random functions can be shortened to on example (with the other left as an exercise for the reader). 3 pages saved.

Excursion into using the distance function in the "For-Loop" section can be left as an exercise for the reader. 2 pages saved.

The section on creating your own replacement algorithm for the random function can be omitted (or again, left as an exercise). 4 pages saved.

The whole bouncing ball section could be omitted. 17 pages saved.

Plus the savings that @bilderbuchi https://github.com/bilderbuchisuggested from tightening up your print-outs and resizing images. This will depend on whether you try any of the above mentioned omissions. I could see you saving a lot of pages this way. 10 pages saved?

That's a potential >40 pages saved without talking about ways to tighten up explanations.

Reply to this email directly or view it on GitHubhttps://github.com/openframeworks/ofBook/issues/40#issuecomment-38127369 .

[bilderbuchi]

So, I have found a way to scale all images in the pdf to 70%. Most images profit from it, but others obviously not (the Kernigan&Ritchie one for example). The whole book shrinks by about 5% (or 20 pages), and layout looks better. Unfortunately, there's no way to prescribe image width in markdown or pandoc, so the probably best way will be to leave the size untouched, and scale with the pixel dimensions of the images themselves.

[mikewesthad]

@bilderbuchi I don't have it set up on my machine or I'd answer the question myself, but how does pandoc handle HTML embedded in markdown? Throwing <img /> tags into our markdown would give us a hacky way to resize images (even though it breaks some of the human readability goals of the markdown format).

@jtnimoy It is admirable (and desirable) to equip readers with zero programming experience with the C++ knowledge to tackle the rest of the book. I think that can still be the goal even when working within a page limit. It's just more about trying to be concise. (If it's any consolation, I'm struggling with the same problem of condensing my chapter.)

[bilderbuchi]

yes, using plain html would work, but as you said, this kinda destroys the point of markdown in the first place. Also, I'm not sure how this would affect the pdf output (i.e. if pandoc translates the html portions into proper images.

[mikewesthad]

Understood - yeah, scaling the pixel dimensions of the images themselves is easy enough to do.

[jtnimoy]

so many of my outputs are slender lists, i bet i could reduce the page count in a big way if I adopted a 2-column system for those outputs, where I allowed the writing to exist on the right side.

[jtnimoy]

Dear OF Community -

My name is Rebecca Shostak and I am Josh Nimoy's partner. My degrees are in Graphic Design and English Literature; although I grew up as the daughter of a successful Silicon Valley entrepreneur and software developer, I do not have a lot of coding experience except for one quarter of Processing at UCLA with Casey Reas and a proficient level of Javascript which I acquired recently from Codecademy.com.

I have been working hard with Josh to condense his OFBook chapter on C++ to meet the requirements all chapters are subject to. As someone who has never learned any kind of C before, I find that the more abridged the chapter becomes, the much harder it is to follow, and pay attention. I enjoy Josh's anecdotes and examples because they make the subject matter clear and understandable for someone who is not so code-literate. I completely understand that it is a difficult position for everybody in trying to keep the book from getting "wild and woolly" but being useful and informative at the same time.

Just from an outsider's point of view, I might suggest breaking out the introduction to C++ into its own mini-book, or making a knowledge of the language a pre-requisite before one should read the OFBook and keeping Josh's chapter to a more conceptual, broader overview of C++ in the context of OF rather than trying to teach the language in such a short span of pages.

That being said, I think what you are doing is absolutely wonderful, and will be of great help to many of us who want to learn creative coding in a more fun, intuitive way. I wish you all the best of luck with it and hope my comments are useful in some way.

[ofZach]

Hi Rebecca --

thanks for the message. @jtnimoy would you be interested in breaking out these chapter into their own mini book? Also, since I think your voice is really important, including an excerpt from that in this book since I think it would be really helpful for people? I don't want you to struggle too much for making your chapters fit here and if you do your own book with this material you can give it the space you need. what do you think?

[brannondorsey]

I have a bit of a worry that removing @jtnimoy's chapters from ofBook would make the book sufficiently less approachable for people who have little to no experience coding.

[ofZach]

agreed, which is why I still feel like we should try to include an excerpt if reducing the page count is a problem here. I am fine either way, (a) try to reduce the page count to something reasonable or (b) include an excerpt from this chapter and pull the rest out to it's own mini book. It's just not fair to the other authors in this book to have 100+ pages, since we are all going for 25 or so, and it's definitely not fair to editors and designers. It would be like talking for an hour when everyone has a 15 minute spot. What I think is better is try to find an excerpt, and at the end say, "for more info, see XXXXX". We can't cover all topics throughly here, this is more like a "sampler", like in the old days when you would get a cassette that includes a track from different bands. You wouldn't hear their whole album, but it was enough of a taste to get you excited.

[jtnimoy]

hey there,

A "teaser" excerpt in ofBook sounds like the way to go! Specifically, the first 20-30 pages of the work, (highest level advice, comment syntax, function structure) plus an additional paragraph explaining about a companion book, how this chapter grew too large, and why it's so difficult to fit the entire subject into a 25 page chapter.

Meanwhile, for the companion C++ intro book, I'll bring back what I had trimmed out, reverting back to a previous version with more examples, and allow the thing to flower out into the right size so people stop telling me it's too brief. I don't mind continuing to have the book be a part of the ofBook project, as long as that doesn't strain your resources! So if 25 pages is all you're willing to handle (which is perfectly fine with me), I'm also happy just taking the book-size edition elsewhere, making it my own investment from here on out.

The piece has benefitted greatly from this community's editing contributions, and is born from this community's sensibilities, which is why I consider it to be a companion book, but I also get that budget is budget. So, please let me know if you can support this new direction and we'll go from there.

Either way, I am forever grateful for this opportunity to contribute, and as always, I enjoy involving myself with the OF community in any way that I can.

I have one more layer of edits before midnight. best J

On Mon, Mar 24, 2014 at 4:22 AM, ofZach notifications@github.com wrote:

agreed, which is why I still feel like we should try to include an excerpt if reducing the page count is a problem here. I am fine either way, (a) try to reduce the page count to something reasonable or (b) include an excerpt from this chapter and pull the rest out to it's own mini book. It's just not fair to the other authors in this book to have 100+ pages, since we are all going for 25 or so, and it's definitely not fair to editors and designers. It would be like talking for an hour when everyone has a 15 minute spot. What I think is better is try to find an excerpt, and at the end say, "for more info, see XXXXX". We can't cover all topics throughly here, this is more like a "sampler", like in the old days when you would get a cassette that includes a track from different bands. You wouldn't hear their whole album, but it was enough of a taste to get you excited.

Reply to this email directly or view it on GitHubhttps://github.com/openframeworks/ofBook/issues/40#issuecomment-38433302 .

[mikewesthad]

I agree with @brannondorsey on needing some form of C++ introduction in the book and with @ofZach about managing length.

@jtnimoy, it's your call as to what you want to do. When I build the PDFs of your chapters from the master branch, it's clocking in at 50 pages for chapter 2a and 56 pages for chapter 2b. I think that two 25 page versions would be reasonable, but I get it if you'd rather create a "teaser" and break out an unabridged version into some sort of companion book that is your own thing.

If you are going the "teaser" route, I'd love to see a combination of high level concepts (namespaces, scope, control statements, etc.) and syntax (for( int i=0 ; i<100; i++){ }, etc.). I'm thinking of something that would give the novice coder just enough of an orientation that they could follow along with the next few chapters via googling unexpected code. I don't think that just taking the first 25 pages of chapter 2a (as they are now) would do that.

[brannondorsey]

I think a brief coverage (conceptual + code) of:

• variables
• functions
• conditionals
• loops

Is all that is really necessary. It is a shame seeing @jtnimoy chapter being cut so much though. It was truly thorough and enjoyable.

[jtnimoy]

Thanks Michael, I think we're going teaser, which will be the first 20 pages of the larger work, modified to talk a bit about syntax details. Call it a double-teaser - partly the most important high level stuff, and partly the most important low level stuff. The entirety of it will be provided elsewhere, probably online at first, and talk of a physical print will be a separate discussion for later.

On Tue, Mar 25, 2014 at 1:12 PM, Michael Hadley notifications@github.comwrote:

I agree with @brannondorsey https://github.com/brannondorsey on needing some form of C++ introduction in the book and with @ofZachhttps://github.com/ofZachabout managing length.

@jtnimoy https://github.com/jtnimoy, it's your call as to what you want to do. When I build the PDFs of your chapters from the master branch, it's clocking in at 50 pages for chapter 2a and 56 pages for chapter 2b. I think that two 25 page versions would be reasonable, but I get it if you'd rather create a "teaser" and break out an unabridged version into some sort of companion book that is your own thing.

If you are going the "teaser" route, I'd love to see a combination of high level concepts (namespaces, scope, control statements, etc.) and syntax (for( int i=0 ; i<100; i++){ }, etc.). I'm thinking of something that would give the novice coder just enough of an orientation that they could follow along with the next few chapters via googling unexpected code. I don't think that just taking the first 25 pages of chapter 2a (as they are now) would do that.

Reply to this email directly or view it on GitHubhttps://github.com/openframeworks/ofBook/issues/40#issuecomment-38614414 .

[bilderbuchi]

Also, liberal linking to other online resources would really be helpful, there must be loads out there for c++. Btw, to me as a non-native speaker, "teaser" implies incompleteness (double-teaser even more so :D) - shouldn't this rather be an "excerpt"? I'm not sure how well the OF book is served by just including the first N pages from another work? (E.g. if I had just included the first 20 pages from the ProGit book in my chapter, it wouldn't have ended up very useful)

[tpltnt]

Is this issue still relevant given that one year has passed and things moved along? Please speak up until 2015-06-01 or otherwise i am going to close this issue.

[ofZach]

I think this issue is resolved....

[roymacdonald]

+1

Roy Macdonald +569 8248 8478

On Fri, May 1, 2015 at 1:01 PM, ofZach notifications@github.com wrote:

I think this issue is resolved....

— Reply to this email directly or view it on GitHub https://github.com/openframeworks/ofBook/issues/40#issuecomment-98178093 .