I recently put a question on Twitter asking about the difference between an experienced/advanced developer’s “fluff” and and a beginner’s learning tool. The replies I got a indicated that there are at least a couple of different perspectives out there depending on which angle you take as well as where you fall in the beginner-to-advanced experience levels. While there weren’t hundreds of people replying to that tweet, there were enough that I wanted to do a quick post to put them together and extend the question to my blog readers.

My initial tweet:

Would you agree that what some call “fluff” in tech reading/writing, others might call previously unknown info (a.k.a. “learning”)?

A more detailed version of that question with more than 140 characters allowed:
Within many tech books, you’ll find explanations of topics that advanced developers have known for years but beginners have never even known existed. While the simplest answer is to look at the target audience of the book (beginner, intermediate, advanced), the question still presents itself within smaller breakdowns of those experience levels. To take the middle ground, let’s say the book in question is targeted at the intermediate level and that one person from each of the three levels is reading it. Does the beginner dev view the explanation of certain topics as useful information while the advanced dev views it as nothing more than regurgitated information from places like Adobe livedocs? Based on the responses I received, I think the answer may not be a straight up yes or no. So here’s a general breakdown of the different views I’ve seen. They all make complete sense to me if I step back and view them with different thoughts. I’d love to hear more so feel free to add your point of view to the comments.

Definitely fluff
There were a few people replying that felt this kind of information was undeniably considered fluff. They want to get to the meat of the information on which the book was written. If they came across anything they didn’t understand or already know, they would rather turn to livedocs, APIs, etc.

A “necessary evil”
Another thought was that it may be fluff, but someone is learning from it. While reader A may come across information of which he is fully aware, (s)he tends to skip past it without thinking too much of it and knows that reader B may learn a quick lesson while reading the book. (I think I favor this one)

One stop learning
Some people look at it as a sort of “one stop shop” where they could get everything they need without putting the book down. If a developer is reading a book which is covering topics that developer has never worked with, they can learn it all right there. This line of thought may seem a bit lazy on the surface, but may also be efficient for the lesson at hand. If a beginner developer is reading about classes but has no idea when to use private vs protected, they don’t have to stop reading the book to go look it up online. Instead, they get the explanation right there in the book and they continue on with their learning.

So that’s it. There’s the question and those are the general thoughts people presented as answers. Now it’s your turn. How do you view that type of information in a tech book?

Enjoy this article?

Yeah, there’s always a question of level. An advanced book should skip many of the minor details, a lower level book would need to spell everything out. With an intermediate book, it can be a tough call. I’ve protested comments from tech reviewers and editors before, where they wanted me to describe some small detail in more depth, but I felt that based on the particular subject, the user should already be familiar with the detail they wanted me to address. Sometimes I won, sometimes I lost.

I tend more towards the side of “not fluff”. Your post made me think about the book I just recently finished and how much of it some might consider fluff. Another factor that should weigh into what information an author puts in a work should be the intended audience’s development background, not just skill level. That a programmer might have many years of C++ dev under their belt does not guarantee a seamless transition to Flash, so one man’s cruft is another’s gold.

I tried to weigh lower-level knowledge towards the beginning of the book, for two reasons:
1) Advanced users can look at the table of contents and know that the first couple of chapters could maybe be skipped based on the information inside.
2) While there’s no narrative drive behind my book, I do think of the information in it as a progression, building one idea on top of another. If someone wanted to read through my book from page 1 to page 335, they *should* (as in, Dear God, I hope) feel like they’ve moved through a single, cohesive work.

Everyone approaches a subject differently, based on their background and experience. No one person knows EVERYTHING about a topic – if they did, they shouldn’t be wasting their money on books.

To the scenario you mentioned above about people who prefer to use the LiveDocs or APIs, who are these gluttons for punishment? I’ve found more than once that the Adobe’s documentation leaves a lot to be desired, particularly for newer features. One example was when I was researching RTMFP for the book – some of the descriptions of methods and properties in the docs are laughably bad.

We faced this issue when writing Professional Adobe Flex 3. The way which I and some of my co-authors solved it — since I aware of this issue from years of reading Flash books, as a beginner right through to where I am now — is to take a topic most would consider basic, like, say, using MXML and ActionScript together, and write about it in more depth than most sources do.

For instance, even though it is not considered good practice, most beginners and some advanced people might not be aware that you can code actionscript right inside of an MXML property tag. What Moock did with basic ActionScript when he wrote Essential ActionScript 3.0 is what makes this book a well-read classic to this day, nearly four years later, and probably won’t be obsolete for some time to come.

So it is possible to write a book for a wide range of skill levels. And yeah, the beginner will be intimidated by some topics, and the advanced reader will skim through some stuff. A tech writer needs to be an extremely detail-oriented person and know how to communicate that detail in a way that is succinct and useful.

If the book is intended for a different skill levels, then two things need to be left out: step-by-step instructions in basic how-to style, unless you’re describing an uncommonly known technique. And describing topics without any code: your advanced users may be able to follow, but intermediate and beginners will be thoroughly annoyed.

On the other hand, the author needs to avoid the temptation of “code dumps,” or pages and pages of code which do not directly contribute to the technique described: it bores the hell out of advanced readers who already got the point five pages ago, and annoys the beginners, who may actually think they have to type all that in. Give enough code to cement the concept, and the reader can go to the download site for the full application (although we do have a bit of a whopper on page 510 that slipped by 😉