Closed mikewesthad closed 9 years ago
roymacdonald
commented
10 years ago Hey Mike, I really appreciate your feedback. I'd say that I mostly agree with everything you mention. And as you said, as it is still incomplete several things you said I already had thought of it, yet there are several others that are really helpful. I guess that during this week I'll finish the chapter. all the best!
tpltnt
commented
9 years ago Hey @roymacdonald, is this chapter already updated? I am asking because i am currently work through it to do fixes where appropriate.
roymacdonald
commented
9 years ago Hi @tpltnt , yes. it is ready. At some point @ofZach took out the second half of it as it was a bit more about oop with the idea of putting it back at some point, either in this same chapter or another one. Yet, so far it is ready for the project setup. Just fix whatever you consider appropriate. Many thanks best
I know @Onna-no-hito mentioned focusing on the Animation chapter and beyond, but I wanted to weigh in with some feedback on this chapter since I think it is a very important one for beginners.
Disclaimer. @roymacdonald, since much of the draft is missing (as you mention in your last commit), I realize some of the feedback might be things you are already planning on doing.
Anyway, feedback:
I like that you are trying to explain what openFrameworks is with a spatial analogy. Thinking of openFrameworks as a room in your house probably makes the concept more inviting for beginners to approach. At the moment though, the analogy didn't quite work for me. It's not exactly clear to me how you are trying to map the IDE, openFrameworks classes/functions, OOP, etc. onto a kitchen. Here's what I'm getting: The IDE is the whole kitchen? Counter top for coding, stove for compiling, etc.? openFrameworks fills the pantry with ready-to-go ingredients? Then you mention fast food and how it doesn't taste as good as homemade food. So is fast food then some third party C++ library that provides a sloppy solution for some task?
Some of this could be solved by clearly stating the analogy in your first section. Still, some of the problem results from the analogy becoming confusing when things get detailed. It needs to be immediately clear what is part of the analogy and what isn't. Aside from the taste of fast food vs homemade, you go into the details of killing a cow and growing vegetables. Here is where the analogy started to get muddy. I think the underlying concepts would be clearer if you tackled them directly, rather than via an analogy.
Instead of talking about a burger you could do something like the following. Ask the reader to imagine some project (e.g. detecting faces from your webcam and drawing masks). Then you explain what you would have to do if you were to start from scratch: learning how to read the webcam, computer vision, drawing polygons, etc. Then you explain the head start that you get if you approach the same project with openFrameworks: webcam access, opencv, drawing, etc.. If you explain the concepts in simple terms (like talking about the webcam without relying on the word "driver", etc.), I think the advantages of the "OF Pantry" are immediately graspable to any reader.
As for the overall structure of the draft, it looks like you are packing a lot into the chapter - super, super useful things like IDE guides and an overview of openFramework's libs and addons. All of that is invaluable, but I think this draft of the chapter would be hard to approach for a beginner. Your chapter comes right after the C++ chapter. The C++ chapter takes place completely inside of ideone, so a complete novice reading ofBook will have no idea about getting set up with openFrameworks. Your chapter starts off by pointing to the installation guides and then says to test "that installation went fine, by opening any example, compiling and running it without problems." The guides (or at least the win guide) don't explain any of the following: how to find an example, how to open it in the IDE, how to compile it, how to verify that it ran without problems, how to troubleshoot any errors, etc. It would be a huge plus if your chapter could walk users through that process. You don't have to walk through the installation, but everything after that point would be great. Tell the reader where to find the examples (you do this, but it comes in the section after you tell them to run an example). Direct them to a specific example and tell them what it should do, so that they know what it looks like when there aren't any errors. (It also gives you an excuse to include a pretty screenshot from an example.) You could mention some common install mistakes, or at least, direct the reader to troubleshoot using the forums.
After the installation is verified, I might even have the reader build their own blank project with the project generator. It isn't as exciting as running an example, but it gets the readers hands dirty, and it is essential to becoming comfortable with the openFrameworks workflow.
After that, then you can move into your "OF Structure" section. I would suggest reordering the way you explore the root directory to match the order in which a beginner would explore these things. Something like: 1) apps + project generator, 2) examples, 3) addons, 4) libs and 5) other + scripts. That way no one gets overwhelmed by trying to wrap their heads around all the addons before they know the basics.
For your "OF Pantry" section, it might make sense to include a picture here. If you are sticking with the pantry analogy, could you organize all of this information into a visual diagram of a pantry? Something simple like throwing the information into a graphic of a shelving unit. It would give readers something to grab onto and make the analogy concrete.
The info you have listed at the very end of your draft is all great. Explaining why there is both a header and a source file answers an almost universal beginner C++ question. The anatomy of an openFrameworks app helps to orient the reader to what they can do. And the one about peeking into other's files is very important because you can empower readers to not be afraid of reading code. This section could be expanded to explain how to look through the openFrameworks libs when something isn't working how you expect.
So, again, I realize the draft is incomplete. It is chock full of goodies! But I think the organization of it needs to be shifted around a bit to make it accessible for the beginner - especially since your chapter is so important for orienting new users in the landscape of openFrameworks.