5 ms·
I like the new structure much better! Now, I'm in no way a writer. English isn't even my main language.. So take this next point accordingly: Unfortunately, I
by mkishi 12y ago
I like the new structure much better!
Now, I'm in no way a writer. English isn't even my main language.. So take this next point accordingly:
Unfortunately, I get an even more condescending vibe from this draft than I got from the book. Not as in "I'm an expert and you're treating me like a newbie," but as if I was a kid instead of an aspiring Rust programmer (beginner or otherwise). I wish I could point out -exactly why- I get this feeling, but I'd be lying.
I do think I'm starting to see a pattern, though, that perhaps contribute to this gut reaction. The pace between concept introductions is odd, somewhat erratic. At times, in one line you're talking to a complete novice programmer, and the very next you assume they know other languages and general concepts [1]. Other times, you take some basic knowledge for granted and explains it right after [2]. I know it must be very hard to find the right balance for your target audience, but I found these jumps very jarring. For what it's worth, once you get past the introductions you pick up a more to-the-point-explanations rhythm and that reaction goes away.
[1]: For example, after several paragraphs and two code snippets to introduce the concept of 'variable bindings' in a novice-friendly way, even going as far as (somewhat) explaining what system and functional languages are, the text suddenly assumes I know about program execution and what a control flow structure is?
> As you know, a computer program is executed line by line. At least, until you hit a control flow structure, anyway.
This line was specially off-putting. After all that explanation, the assumption I'd know this made me feel like a kid. But I can only imagine how inaproppriate I'd feel if I didn't know. Given the novice level of the text up to then, the 'as you know' sounds very out of place.
[2]: The very next paragraph, we go over a program with one variable binding line by line. And then, it's assumed I know about scopes. But after that they are explained anyway. I realize this is a way to go over every concept, even if one already knows them, but it feels odd! Both beginner and experts would understand a plain explanation. But this back-and-forth about how to present concepts doesn't work -- for me. It'd make more sense to read straight-forward explanations of what I already know than these "as a programmer, you know that x," mixed with even simpler concepts being introduced as new.
This sounds harsher than I planned -- I'm no writer afterall! But, really, despite these gut reactions, the Rust book is turning into one of my favorites. Thank you for all your work!
- steveklabnik 12y ago> I wish I could point out -exactly why- I get this feeling, but I'd be lying. It's hard, for sure. There are certain sentence structures that strike certain people this way, and my style sometimes triggers them. For example, "basically" has no negative connotation for me, but really gets some people going, so I've been eliminating it wherever possible. I wonder which aspect does it for you... thanks for the brain dump, this is helpful.