[xrd]

I wish there was a way to upvote something 10x once a month here. This would be the post I use that on.

When I was writing my book my editor asked me to remove any writing about mistakes and changes I made in the project for each chapter. I had a bug that appeared and I wanted to write about how I determined that and fixed it. They said the reader wants to see an expert talking, as if experts never make mistakes or need to shift from one tact to another.

But, I find I learn the most from explanations that share how your mental model was wrong initially and how you figured it out and how you did it "more right" the next time.

That's really how people build things.

[fnord123]

>They said the reader wants to see an expert talking, as if experts never make mistakes or need to shift from one tact to another.

Your editor was very fucking wrong.

[natefox]

So, so wrong. How did (s)he think experts get so good? Isn't the phrase `the master has failed more times than the apprentice has even tried` well known for a reason?

[a1369209993]

> the master has failed more times than the apprentice has even tried

I've never actually heard that one before, but it's so very, very true.

[emerongi]

It obviously depends on the type of the book and the reader's expectations. It just might not have been the type of book where you write about things like that.

[ohyeshedid]

>It just might not have been the type of book where you write about things like that.

I think that'd be more of the author's choice, instead of the editor.

[gridlockd]

> Your editor was very fucking wrong.

The editor is completely right in what they were saying. You just want them to be wrong, because you'd prefer to live in the fantasy world where they are wrong.

Let's say you go to get a surgery. You don't want the doctor to tell you about all the times they fucked up and what the awful consequences were. It doesn't matter that they're probably a better surgeon now, having learned from their mistakes. Psychologically, you need that person with the sharp tool poking around inside your body to be a superhuman.

To a lesser degree, the same is true for any expert. Of course everybody makes mistakes. Notice the de-personalization in the word "everybody". You can talk about the mistakes everybody makes, or those ones that many people make. If you talk about your own mistakes however, you lose the superhuman status. There may be a few situations where that somehow helps you, but not when you want to sell books.

[sokoloff]

I sure do want that surgeon to have been presented/instructed on the common ways that surgeons before them have made mistakes and how to avoid or overcome them.

That they won’t tell me (the patient) is quite a different question from whether they got the material from someone more experienced in their primary or continuing medical education.

[gridlockd]

The situation is different, the psychological effect is not.

[justinclift]

> Let's say you go to get a surgery.

Shouldn't that be more like "Let's say you're learning to be a surgeon."?

For that situation, the person they're learning from discussing problems they hit and how they solved them does sound like it would be very useful.

[gridlockd]

> Shouldn't that be more like "Let's say you're learning to be a surgeon."?

No. It is an exaggerated example, because I am illustrating a psychological effect.

The point is that you are consulting an expert, and you don't want that expert to tell you about all their mistakes, because your mind is now occupied with doubting that expert. It's not rational.

> For that situation, the person they're learning from discussing problems they hit and how they solved them does sound like it would be very useful.

It's useful to present common mistakes, but mentioning who made the mistake is both irrelevant and damaging.

[fnord123]

>The point is that you are consulting an expert, and you don't want that expert to tell you about all their mistakes, because your mind is now occupied with doubting that expert. It's not rational.

Sometimes books are written for entry level people (to the technology or topic) and they're written in an authoritative tone. But I work with people who write books. And I read their books. I don't read them like some kind of expert oracle distributing the blessed texts. I read them as a work of documentation from a friend or colleague, so I don't really feel this veneer of expertise is necessary.

Sometimes the experts try hard to scrape away the veneer of expertise by adding side fluff like in Learn you a Haskell for Great Good. Or, Alex Crichton, who is undoubtedly an expert in Rust and compiler technology giving this talk where he keeps saying things like "it does a process called quasiquoting which doesn't make any sense to me", "I don't know what hygiene means"

https://www.youtube.com/watch?v=g4SYTOc8fL0

[gridlockd]

> But I work with people who write books. And I read their books. I don't read them like some kind of expert oracle distributing the blessed texts. I read them as a work of documentation from a friend or colleague, so I don't really feel this veneer of expertise is necessary.

Yes, you feel that way. You feel like you're a rational person who values humility, whose judgement isn't clouded by the effects that I am describing.

Well, maybe you really are that person. It doesn't matter. We cannot assume that the buyers are such noble beings.

[justinclift]

> The point is that you are consulting an expert, and you don't want that expert to tell you about all their mistakes, because your mind is now occupied with doubting that expert. It's not rational.

In the situation where I'm consulting an expert - hired to fix a problem or find a solution - then I'd tend to agree with you.

But when I'm reading text from a person in my field in a subject area of interest (eg learning from a book), then I definitely want to hear of things that went wrong, and how they fixed them.

I think they're two different situations, and the one you described above isn't the correct one for a person who's bought a book to learn from.

It could just be us valuing different things in our learning though. :)

[robertlagrant]

A patient is not consulting an expert. A medical student is. Who would be very keen to hear some war stories.

[fnord123]

I wonder if we're on the same page. Should a book on a programming language discuss compilation errors and how to interpret them? Should a book like Effective C++ (afaik the most popular series of books on C++) exist?

[gridlockd]

The answer (yes) is already in my reply, in the second paragraph.

[0xFF0123]

The book is not presenting to the patient, the book is presenting to another surgeon. If I was a surgeon, I would find value in learning about previous mistakes, and thankfully in programming as a general rule the cost of error is lower (but still a valuable learning).

[bsd44]

"The book is not presenting to the patient, the book is presenting to another surgeon"

I like this analogy and I agree that the previous person saying the publisher was right, completely missed the point.

[Igelau]

Found the editor!

[Leonid99]

Most books frame this as "one common mistake is ...". I always understood this phrase to mean that the author has personally made this mistake more than once.

[drvdevd]

Agreed. The entire expertise of programming is based on the willingness to find these sorts of issues and fix them. Over and over, for your entire career.

[xrd]

Obviously, I agree with you!

I also think this is the way the majority of tech books are written.

Can you think of another where the author goes from mistake to mistake and then finally gets it right?

I believe there is a space in tech writing for this kind of writing, but it is not something traditional book publishers believe.

This was an O'Reilly book by the way, with really good editors and a really good editoral process.

That editor was right most of the time, IMHO.

[fnord123]

>Can you think of another where the author goes from mistake to mistake and then finally gets it right?

Not a book, but Raymond Hettinger often presents in this way and it's fantastic: https://www.youtube.com/watch?v=wf-BqAjZb8M

[drvdevd]

Most (in-depth, technical) security books follow this sort of thought process- I think. “A big hunters diary” comes to mind.

[fnord123]

Ignition! A history of liquid rocket propellants.

Little Lisper, Little Scheme is a conversation style that discusses a lot of false starts.

{Coders|Founders} at Work has a lot of frank talk about early mistakes people make and their pivots.

[barrkel]

s/tact/tack/

Tact means skill in dealing with other people, particularly in sensitive situations.

Tack has to do with sailing boats into the wind, and crucially "changing tack" means changing direction.

[xrd]

Thanks, I'm glad I had you as an editor this time! I never noticed that before.

[namelosw]

I hate this so much. But it's so common.

I was told not to mention the caveats, instead, render a confident image for the team many times in my career.

It's like doctors suggest their patients to use some drugs without mentioning any side effects.

It reminds me of the video[0] which asks the developer to draw red lines with blue ink, while the project manager keeps pushing the developer like "You're the expert, of course you can do draw red lines with blue ink!".

[0] https://www.youtube.com/watch?v=BKorP55Aqvg

[raverbashing]

> asked me to remove any writing about mistakes and changes I made in the project for each chapter. I had a bug that appeared and I wanted to write about how I determined that and fixed it.

Your editor is right. Not because this information is not interesting.

But it is distracting and off-topic to go off a tangent every now and then. Especially for someone just learning the stuff, it will confuse them more than anything else.

[m463]

years (and years) ago, if I wanted to learn a new computer technology or language, I would pick up a book and learn it.

One language that didn't go how I expected it was applescript.

The book on applescript (from o'reilly I believe) was necessarily different.

Instead writing "normal" top-down programs, applescript hooks into the OS from the side.

Many books can concentrate on what you can do, but the applescript had to do everything by example. This is because all of apple's applications expose interfaces that you have to figure out on the fly.

I had to learn a different way from that book, because it necessarily concentrated on "how" instead of "what".

[mgkimsal]

personally... I'd like to see that sort of info, but typically not in the middle of a chapter/section. make a note or call out in the text pointing to a section on why/how you got to the 'correct' position. That info is often helpful info, but can disrupt the flow of the 'good' information.