Alright, fighting a little frustration here. My weekend is devoted to 2 chapters of this book as well as another article for <a href=”http://www.communitymx.com”>CMX</a>. However, the point of this post is that I’m trying to fight disillusionment here. I’ve found some tech books either rehash the documentation with tutorials in a pretty cover, simply rehash the docs and make corrections, or ignore them altogether (for good or ill). Well, I don’t know how my editor feels, but this is some bs. I am NOT going to rehash the documentation. If people buy this book, I want them to learn something they couldn’t read in the documentation. I think the book is supposed to be all inclusive, but to me, why? I’ll find out Monday, I’m sure, but in the meantime, I’m just going to rehash the docs only where I think something needs to be included. Everything else, you can read in the docs. I refuse to add content strictly for the sake of adding content. I don’t think that’s fair to my readers.
…am I wrong? Is this what your supposed to do in a technical book? Rehash the docs? If so, I’m deviating from the norm, period.
What book are you actually writing on?
Don’t know if I’m allowed to talk much about it, so I’ll just say it’s a big arse book on Flash Communication Server MX. I’ve got 4 chapters in it. One chapter in particular is really nitty, gritty details, and that’s the one I’m having problems with. Granted, I have some experiences to share, but it’s miniscule on such a … dry subject. The other 3 chapters are cool, it’s just this one already has extensive documentation on it.
Unfortunately, most books do the rehash thing and get away with it. I think there are obviously great reference books that some could say much of which should have been done in the docs, like ASDG2. However, there is no pretense about what you’re buying, and I think Colin does an excellent job by providing context around the reference material.
My central point is to hit the objective of the book, which, in fact, may rehash a fair amount. Is the book about a topic which is adequately or inadequately explained in the docs? With all the material (docs/tutorials/forums) on the Web, I personally am very hesitant about buying a ‘reference’ book unless I can see the value added quickly.
I think the best thing to do is to give real, practical examples, even if it’s rehashing the facts that appear in the documentation in a larger context. Many times in the official documentation, you don’t see how things relate to one another, and so it’s hard to understand how to apply the concept. If you can explain the concepts in terms of a big picture, that is, how things can fit together, then it makes more sense to have material allowing someone to drill down once they grasp the big picture.
Please indulge me for a moment with one gem. I was talking with someone about setInterval and how it really didn’t get you close to the interval in some cases (and resulted in interrupts at half the rate!). The person said “well, it works the way the documentation says it does.” I agreed that in fact, it does work like the documentation says. However, that functionality is not at all intuitive for those cases, and people can really have problems if they don’t recognize when it fails to meet their assumed needs. The topic of using timers would be a great subject, even though most of it would center on how to use (and how not to use) setInterval.
Ideally, the documentation should provide how to use something and the motivation, but often it lacks a serious effort at the motivation part. That’s where I think books that focus on practical examples are most useful. Authors should not be afraid of challenging the Macromedia docs to point out what the author thinks is a design flaw, or, on other side, a really clever technique. In my book, I made no pretense about that I believe the changeHandlers and the event model in Flash MX were inconsistent, and neither really helped in the problem of coordinating complex interfaces.
My disappointment with technical books occurs when the purpose is said to be one thing, and then it adds 200 pages of reference materials that I could have found in the docs. Or it adds the use of some software that you have to buy (of course unless it was obvious immediately when I picked up the book), or otherwise is not readily available.
Thank you for your insight and comments!
The majority of my topics are not covered in the documentation. Utilizing Flashcom components, creating them, and utilizing that stuff with Director to me is a scarce subject. However, administering Flashcom is not. There is a ton of good information in the documentation, hence my problem. I only feel like summarizing it with additions of my experiences with it. The issue is that since the issue of administering a Flashcom server is more technical, and less about developement, you really need those technicalities.
Actually, the <b>real</b> problem is that I don’t know the true nature of the book’s goal in regards to this chapter. I’ll just have to ask on Monday and modify as needed.
As far as setInterval goes, yeah, it’s jacked. I like it, but it’s in no way close to an audio only Quicktime track utilized in Director for spot on timing of events. Flash, in my opinion, can’t do that. You only have a few concretes in Flash:
– onEnterFrame gets called every frame
– your framerate will not always remain consitent
– only up to 10 intervals can get called per frame
– if an interval takes longer than 15 seconeds, you’ll get that bloody script taking too long error
So, there really isn’t a way to utilize those two ways to get spot on timing. There were a few posts on Flashcoders concerning good timers, but I’ve always made due with what I had. Most were in relation to creating sound mixing programs used in loops.
Since setInterval is not directly wired to framerate, a 1 second interval at 1 frame per second will not get called every frame. If you set it 1 second, sometimes it will get called every frame, sometimes not, and sometimes twice.
If your not creating a sound mixer, though, I don’t see what the problem is. A setInterval calling getTimer every 0 millseconds and comparing with your current time suffices for me. I do see, though, that the docs don’t explain it’s application, and in reference to my issue of rehashing documentation, I see your point.
My purpose is to provide in lamen’s terms how to use Flashcom components, how to create them, how administer Flashcom, and how to utilize Flashcom with Director. To me, if you want specifics, look in the docs. I see myself as an interpreter for those who have a hard time comprehending and applying (applying like you were talking about) it to the real world. Since I’ve already gone through this bs, I figured I could save a ton of people a lot of time and heartache.
Your insight and suggestions help a lot. Thanks! I’ll have chew on them some more.
I’m curious what books are doing that. Perhaps they’re doing it by accident–I’m just trying to give the benefit of the doubt.
Anyway, there’s nothing wrong in referencing or pointing readers to the docs. No sense in reinventing the wheel. Even if your book did have the same examples from the docs, one would hope you’re providing more practical application. If nothing else, people expect cohesion in a book… almost a linear story. Well, reference books might be an exception.
Personally, I have a hard time actually READING technical books (my own being the hardest on my patience). However, the thing that I see the most distracting in books is when a multi-author book is obviously not coordinated. There are some good ones, but a few have no theme. I believe a book should be able to be summed up in one or two sentences.
The hardest thing for me–by the way–isn’t avoiding plagiarism, but rather remaining concise. I just want to get a point across and I’ll sometimes take a few extra pages. I feel like saying “if you understand what I’m saying jump ahead here”.
Concise writing is the hardest in my opinion.
Thanks,
Phillip
P.S. Who says you can’t say what book you’re doing?
ActionScript in a Nutshell v1. It had an entire back devoted to a “correct” version of the documentation. Nobody who used Flash utized the help, but instead referred to, “…on page 384 of ASDG, it cleary states that XML.onLoad blah blah blah…”. It was rehashed documentation, but Moock corrected things, and added his own examples.
From the other side of the fence, there have been a ton of books, wish I could give you titles, who talk about how to make a button in Flash. Honest to God, how many ways can you spin the wording to say how to make a button without really saying how to make a button? They all tell you, but so does the Flash manual.
…but therein lies the issue, I guess. All of this spawns from my personal style of book. Nowadays, I don’t like how too books. If I buy a book, I usually only read a chapter, and instead refer to specific pages of the book to figure out how to do something. This wasn’t always the case, but I’ve gotten good, in my opinion, on teaching myself and consolidating through a lot of un-needed information. Case in point, PHP for the WWW books. I refer to specific page numbers, and one specific chapter to do things. I learned how to code in PHP in one night after my gf couldn’t get a Perl script working. It was Flash with $ in front of variable names. When I hit a snag, I borrowed my gf’s books which she bought the next day. I stole it immediately, but only read 20% of each chapter, and then only about 4 chapters of the 12 chapter book consisting of about 500 pages. Just give me how to call a record set from mySQL, I’ll figure out the rest thanks.
This is not the most effective way of learning, I’m sure. But, recently discovering that I had some developer in me, I like re-inventing the wheel or struggling through some parts to help myself better understand the whys of how things work.
Maybe that personality trait is coming out in my writing, but I feel I only want to write about things that are pertainent to a fellow developer, or even someone who is a designer and has a different mindset. To me, if I can focus on that, I’ve succeeded in telling the reader what they needed to succeed. I’ve never liked docs, but couldn’t live without them. I feel I’m just helping MM out with my spin and experiences put on their docs to better help people be successful. This one chapter, though, is making that 2nd part helpful. Maybe I just don’t hang out with enough admins to know what they’re like.
Anyway, I’m screwed on the concise front. Both of my college professors said I had problems with shutting up. One said if you ask me what time it is, I’ll tell you how a watch works. The other said I should answer the person’s question, period. If the person wants more information, they’ll ask.
…I disagreed with both, of course. Bleh. I at least feel better about you saying that I can point to the docs. That makes me feel… a whole lot better. Still, not sure about the linearty or theme. The only book I saw successfully done (and I haven’t read many tech books, mind you, from front to back) is this D&D book about the Fiends of the Outer planes. Each chapter was done by not only a different author, but a different “type” of author. One was an evil demon, another a gigantic frog from a land of chaos… some with villanous grammar, others with character perks berating their perceived intelligence only until you noticed you’ve read 5 pages of their spiel about things they know. Really well done, but then, that’s TS…er, Wizards of the Coast’s full time job. This to me is just doing my part to help out the Flash Community.
Cool, at least I feel like I’m on the right path again. Thanks, yo.
When I write I find myself on the same boat as you. I always end up explaining too much and don’t know where to stop :) After a few times I got better but I still don’t know when to shutup. It makes it really hard to write too because to explain something simple you end up writing for page after page. I can’t offer you any advice because my choice was to simply not write anymore. But I did want to let you know you are not alone :).
PS I may write in the future but its highly doubtful. I don’t have the time to write a book of my own, and like said above multi-author books are just too disconnected…and of course finally…books just don’t pay off (for me)
Whatever you do don’t write a book like Robert’s FCS book… I’ve never seen a book copy so much out of the already built components and copy so much out of the docs… please!!!
My goal, again, is to help the reader succeed by reading what they need to know. If I add already existing content from the docs, it’s because I am adding my own comments to it, in my own words. I’m trying my best to do good!