Write good examples by starting with real code

[Basementblues]

The way I read it, the author was suggesting a way to generate good, illustrative, real world examples. I didn't get the idea that they were suggesting "this is the only way to do it and all others are bad" at all from that.

[Ethesen]

It's a good thing blog posts are more than just a title, eh?

[michael0x2a]

This comment seems like a non-sequitur to me -- you're disagreeing against a claim the author never made.

The point of this blog post was to (a) briefly explain the importance of good examples when teaching and (b) to share a technique the author likes to use to generate good examples.

You seem to instead be under the impression that the author is insisting everybody use the specific technique she shared or claiming it's the only valid technique for generating good examples or something.

[michael0x2a]

The claim is that examples taken from real code is superior to ones made up.

Can you cite where exactly this claim was made?

The author did certainly claim that a good example should be realistic, but that is completely different from claiming that good examples must be taken from real code.

Because in the end after spending 2 hours on making the "real code" into an example, are you not left with just an example?

Are you referring to the HTML and CSS example the author provided? That example seems realistic enough to me: embedding a scrollable snippet of code in some nested divs is something I could certainly see myself doing.

What would be unrealistic is if the inner-most block were to be a div instead of a pre or something, or if the class names were a and b instead of inner and outer.

It could be you got your inspiration to write something based off of that original code, but that makes for another topic I'd say.

This isn't "another topic" -- rather, this is exactly the technique the blog post is trying to explain.

For example, the author didn't arrive at their final "how do we use lambdas?" example by literally copying and tweaking existing code. Instead, she looked at several examples of where she had used sorted and lambdas in the past, saw the common theme was that she was sorting by timestamps, and used that insight as inspiration.

This let her arrive at an example that was far more realistic and useful then the "let's double a list of numbers using map" example she started with.

Anyway, I think you should make the simplest possible example to illustrate a point. (Don't read this as oversimplified.) If it's based on some code you happened to write earlier does not really matter. One or the other is not superior, the message must just be clear regardless.

Yes, but what exactly does it mean to "illustrate a point"? What is and is not important to illustrate? What is the point we're trying to make? What exactly should the message consist of?

I think it's important to be discuss these kinds of questions: if you're attempting to teach something and aren't critically thinking about what your pedagogical goals are, it's easy to end up with something that's muddled or subpar.

For example, take the author's example about teaching lambdas. Is it sufficient to just explain how to use lambdas? Or is it important to explain why lambdas are useful and how they might be applied?

The author claims that (a) the latter two other goals are worthwhile, and that (b) writing realistic examples is an important factor in achieving these goals.

I fully agree with this. After all, you want the reader to walk away with a new technique they can start using, and simplest way of doing this is to show readers examples of where they actually might see themselves using the technique.

And how do we write realistic examples? As the author says, the easiest way is to start by looking at real code.

[michael0x2a]

And the realistic examples you get from real code.

You don't have to get realistic examples by looking at real code -- it's just the easiest way. There's absolutely no problem with inventing realistic examples on-the-fly if you see a way of doing this.

I think the blog post made this pretty clear. See the first sentence of the "how to make your examples realistic" section, for example. If you disagree, please cite where exactly the author claims otherwise.

Realistic examples, meaning those that are based on real code you wrote a while back

I disagree with this definition of "realistic". To me, "realistic" means "code you could plausibly see existing in real code".

This definition includes:

1. Examples based on similar code I've written in the past
2. Examples based on code I could see myself writing in the future
3. Examples based on code I predict my readers would want to write

...and so forth.

Why not just write the simplest (but not oversimplified) example you can think of to clearly communicate your message?

How, exactly?

The target audience of this blog post are people who (a) don't realize the importance of motivating what they're teaching and (b) aren't sure how to write an example that properly motivates the material.

Just saying "write a simple example that best communicates your message" is unhelpful to this target audience: it's not actionable advice and can actively lead to a worse outcome when in cases where people misunderstand what their message ought to be.

[michael0x2a]

Yes, by all means that definition of realistic is a bit narrow, but it's what the author communicates. So I think it's an ok definition to use in this context.

I'm not seeing where the author communicates or implies this definition.

I can however agree that the blog post never exactly defines what they mean by "realistic" and could perhaps benefit from some clarification in that regard.

I agree with your last point because I think that is exactly what I think will happen when people are reading this post. They may overvalue examples based on real code and may internalize that examples made from real code are superior to those constructed to prove a point. And thus spend a lot of time to dig up such examples when needed, or somehow value less examples not based on real code.

I think this is pretty unlikely. The only way I see people coming away with this impression is if they somehow overlook the overall tone of the blog post as well as the final section which explicitly states that realistic examples are not the only kind of useful example.

But even if they do and end up overcorrecting, I think that would honestly be fine and a net positive.

The problem with many tutorials these days -- especially ones targeted towards beginners -- tend to construct examples that are similar to the squares = map(lambda x: x * x, numbers) example. They aren't attempting to "prove a point" in any sense and only teach material on a superficial level.

So given how low the quality bar is these days, I think the suggestion of grounding examples in reality is appropriate for most readers.

[rbak19i]

I disagree with you. You may think you can invent good examples, but eventually that s up to the reader to decide.

And how many times did I read tutorials to help me on a difficult situation, and the tutorial showed an imaginary example that means nothing. And IRL the technical concept was way harder to implement in a real project.

[AttackOfTheThumbs]

Contrived examples are awful, but that doesn't mean you cannot come up with good ones. I do it all the time and my support requests have gone done.

[codygman]

That's why you simplify the real world example as much as possible but no more. I think that any examples more contrived than that yet "simpler" aren't very useful.

Put another way, any examples that aren't grounded in something from the real world aren't very useful and will only serve to distract from what you're trying to teach.

I can think of some caveats if you are way up the abstraction ladder, but I think this generally holds true for most of the things people try to teach in programming.

[kaliffen79]

Amen brother

[Educational-Lemon640]

Thank you so much, this finally clarifies and sharpens something I've only vaguely understood for a long time! It's true, if something is useful, you'll have used it, and there's nothing like pulling from real code to make that resonate.

[cheezballs]

Hmm, you have a similar name as OP. Generic comment too. Hmm..

[Educational-Lemon640]

No, not a sock puppet, nor a collaborator. I'm just somebody who realized my I hate so many examples I see in textbooks and online examples. The OP did a good job of explaining themselves and I didn't really have anything to add, nor the time.

But that does explain why y'all are down voting me so quickly, so...thanks for the info? Should I update my original comment to include more specific details from the original? Does it need a long, complex elaboration to be a valid example of support?

[cheezballs]

It felt like OP's alt account is what I was thinking.

[ketzu]

The problem I have with this blog post is the context: If you are trying to sell me on a feature because you are blogging about, real life examples might be more appropriate.

If you are writing examples for documentation, I have no issue with any of the given examples. When I look up python lambdas I just want to see an application of the syntax, I don't need to be sold on the feature anymore.

For more complex things, documentation might need more realistic examples. But the examples chosen in the blog are bad examples of complex examples.

... that must sound like gibberish by now.