Pedagogy: pointers or plaintext posts

Replies are listed 'Best First'.
Re: Pedagogy: Pointers or plaintext posts by elusion (Curate) on Apr 08, 2002 at 20:19 UTC
Personally, I like to receive both code and a link to documentation. Most of the time, documentation is easy enough to find. Most of the time it's easy enough to understand. But sometimes it's not. I always try to find the answer for myself before I come looking for help. Hopefully most people do this. If they don't, they're not gonna learn anything anyways. Sometimes it's a matter of knowing where to look. Other times, the documentation is too long or too hard to understand. I've seen plenty of modules whose pod doesn't tell you anything. For that reason, I like to give/receive both code and a reference. A picture's worth a thousand words, even if the picture's actually some code. This is especially comforting to newbies, who may need to have their hands held. However, the documentation will probably have other useful things in it, else that too would just be a code snippet. Remember, also, that resources like Ovid's CGI course are good references. elusion : http://matt.diephouse.com Update: This is my 100th post.	[reply]
Re: Pedagogy: pointers or plaintext posts by mrbbking (Hermit) on Apr 08, 2002 at 20:33 UTC
That's one of the things I love about this place - there's a mix of response types. Whenever there's a module that can help, someone points to it. Sooner or later, someone else posts some code or pseudo code (which may or may not use a module) to solve the problem. The good old saying "Give me a fish and I eat for a day, teach me to fish and I eat for a lifetime" neglects the starving. If I'm starving, there's no time to learn to fish. "I need to eat now, so how about a small fillet while I practice tying knots?" Then, when my stomach is no longer growling, but I'm still hungry, I can concentrate on learning. (See Maslow's Hierarchy of Needs for an in-depth discussion.) In long-enough lived threads, you can usually find some morsels to use now, and references to grow with later.	[reply]
Re: Pedagogy: pointers or plaintext posts by stephen (Priest) on Apr 08, 2002 at 20:49 UTC
It's a hard problem, and one I waver back and forth on. I personally learn best by example. Two or three well-chosen examples will show me an approach or strategy far more rapidly than the most well-written explanation. So I think it's a good thing to provide example code, since I usually can't solve a problem without typing up an example or two anyway. Frankly, the practice I get doing that is part of what makes PerlMonks valuable to me. On the other hand, giving someone a drop-in solution encourages copying and pasting without comprehending. I don't care if someone copies and pastes my example code, but they should understand it. So I try to use toy code. I distill the code snippet down to the simplest example that still shows how to solve the problem. Toy code should run anywhere and not depend on things like databases. It's simpler to understand than an actual rewrite of the original code, and the poster must reapply the knowledge in my reply to their original code, so I don't need to worry about encouraging bad copy-and-paste habits. The exceptions are: Folks that already know how to solve the problem, and are asking about style improvement. I'll happily rewrite their code to do the exact same thing. People who do not post any code at all and do not indicate the (possibly substantial) work they've already put into the problem. Getting newcomers to read the basic documentation is also a puzzle. I don't like flaming people at all; in fact, I hate it. I don't even like downvoting nodes. However, I think that reading the docs is more enlightening than the most spot-on post, because of the things you'll learn while reading them. I will do whatever I can to encourage reading the docs and O'Reillys, using whatever carrots and sticks I can apply. stephen	[reply]
Great Posts Enhance Docs - Re: Re: Pedagogy: pointers or plaintext posts by metadoktor (Hermit) on Apr 08, 2002 at 22:57 UTC
I agree with most of what you say in your post but... However, I think that reading the docs is more enlightening than the most spot-on post, because of the things you'll learn while reading them. I think that a well written post speaks more clearly than the documentation that often comes with code. Sometimes a poster will comment on stuff that might not be included in the docs. At any rate, I prefer reading real bound books to reading online docs unless the online docs supersede the paper ones. metadoktor "The doktor is in."	[reply]
Re: Pedagogy: pointers or plaintext posts by Zaxo (Archbishop) on Apr 08, 2002 at 20:47 UTC
I did some teaching at one time. I found that my presentations were best when I put myself in the student's shoes. By recalling what puzzled or interested me when I when I learned, I could select examples to best effect. What are the hard parts? Anticipate the need to explain them and set up the lesson to emphasize them. Find three ways to explain them. Explain them in advance of using them. What should they already know? Don't assume they fully understand even if they do know about something. Brief incidental reminders never hurt. Examples should be short and as simple as possible. They should be as pure as possible. Avoid obfuscation or additional tricky bits. What use is it? That question is always in the minds of students. Anticipate that, too. Examples should be extendable. Indicate how a code fragment might be used in other situations. I can't claim to always follow my own advice. When I do I usually know I've done well. After Compline, Zaxo	[reply]
Re: Pedagogy: pointers or plaintext posts by footpad (Abbot) on Apr 08, 2002 at 23:22 UTC
Well, since there seems to be a somewhat common theme, here's what I'd like to see improved: Encouraging people to read the friendly docs is fine, however, let's not troutslap them too heavily for it. After all, there are people who don't realize the docs are there or how rich they are. (Sorry, but it's true.) Granted, some people don't get it. Fine. Let's give folks a chance to get it before we hammer them. When telling people how not to do something, please try to include at least a brief (or a link to a fuller) description of what they should be doing instead, preferably one with enough detail to be truly educational. It's all well and good to alert people to their mistakes, but there are some that learn best from examples, rather than failure. When you find yet another instance of a meme, CCP, or commonly-made mistake, please don't dump on the person and then leave. If you're going to warn them off of something, try to take time to point them to a discussion with helpful specifics. If you don't have time, then please trust that at least one of the others will take that time. If you're tired of reading the same-old questions and writing the same old responses, then maybe it's time for a break or to write some new material. We've an everchanging readership and some people may not know as much as you do. (Sorry, but one of the problems endemic to online support is that you will continue to see the same questions asked again and again. Think of it as an opportunity to improve your writing, presentation, and communication skills.) When you discover something that works in more than one situation or something that could help anyone else, regardless of the scope or specificity, please consider doing an appropriate Meditation, Tutorial, or whatever. I know this type of thing takes a lot of time, however, we can't point people to good nodes in the archives if we don't maintain them and update them. When someone appears completely clueless, try to assume that they're simply inexperienced and are therefore willing to learn to do things the right way. Don't just assume that they're morons. Please. Just because something appears to be off-topic is not automatically a reason to consider it. While certain things are off-topic, anything even remotely related can generate interesting replies containing topical information. I'm not saying we should turn this into apachemonks.org, however, there may be value in letting certain obliquely related node remain. Case in point, someone recently posted a node describing certain problems installing a given module. Turns out the underlying problem had nothing to do with Perl, but with the libraries on the machine in question. Yet, a careful review of the POD, README, and the archives revealed no hints to that requirement. Granted, the module's author should have included a Prerequisites section in the POD, however, let's not slap the poster around because he didn't know that a certain set of BSD libraries were out of date. And while I'm on the soapbox, please don't consider nodes that have (good\|decent\|fair) replies. After all, we've all seen threads that started strangely and then evolved into interesting, educational, and relevant discussions. In a sense, this goes back to Turnstep's PerlMonks as Ambassadors. While we've made some progress in those areas, I do wonder how many people have been scared off since that was posted. Tilly once told me that he participated in the community to help give back to it. I'd like to see that ethic continued. Well all have little tidbits and facts we use to get our work done. So, let's share them as completely as possible. You'd be surprised how helpful that can be (or how appreciative people can be when they find those tidbits.) It's all well and good to be asking the right questions; however, I think it's also good to assume that people who take the time to ask for help, request feedback, or otherwise post things are trying to learn. It's certainly a lot less stressful than assuming that everyone else is a clueless moron. --f	[reply]
Re: Pedagogy: pointers or plaintext posts by mstone (Deacon) on Apr 08, 2002 at 21:36 UTC
But am I doing them a disservice? No. Documentation and examples coexist to their mutual benefit. Technically speaking, they participate in a positive-sum game -- having some of both is better than having a lot of either. Documentation tries to provide a global view of the system. If you have a question about the subject -- any question at all -- you should be able to find an answer somewhere in the documentation. Good documentation lists all the system's components, all the connections that exist between components, and all the issues involved in getting components to work with each other. Examples instantiate the documentation. If the documentation is a directed graph, an example is a single path through that graph. Both alternatives have their strengths and weaknesses. Documentation makes sense from the accounting perspective, because we may as well collect everything we can say about a system in a single place. OTOH, that completeness makes it harder to find the answer to any given question. Finding the answer to a specific question tends to require O(n) time, where n is the number of components in the system. You can reduce that to O(log(n)) time if you arrange the documentation in a tree, but only if the reader can accurately predict an answer's location from the higher-level descriptions. Documentation sucks for complex questions, because complex questions involve combinations of components. Combinations expand factorially, so finding all the necessary answers to a multi-part question tends to require O(n!) time. Examples live at the other end of the scale. They suck for completeness, but they're great for giving people answers to multi-part questions. In the vocabulary of dynamic programming, an example is a memoized search through the factorially-large space of possible answers. So for simple questions -- defined as those which involve a single answer -- it's okay to point someone to the appropriate documentation, and maybe the section. That amounts to reducing an O(n) or O(log(n)) search to O(1) time. For complex questions -- defined as those which involve multiple, inter-dependent answers -- sending someone to the documentation is no more efficient than telling someone to use a brute-force approach to finding a longest common substring. It forces them to use an O(n!) process when you could give them an O(1) process again. Yes, people who get examples can become helpless, cut-and-paste coders, but that's not your problem for two reasons: One, you have neither the power nor the mandate to turn everyone into a good programmer. The people who want to be good will go to the documentation on their own, and explore new combinations based on your memoized example. The ones who don't care won't read the documentation anyway. There's nothing you, I, or anyone else can do about that, and none of us want to live in a world where someone could do something about it. Two, the difference between saying "here's an example" and saying "use CGI.pm" is one of degree, not one of concept. When you get right down to it, using modules is just a disciplined form of cut-and-paste coding. If you look at any standard argument for using CGI.pm, you'll find what amounts to an argument not to go back to the underlying documentation (HTTP, MIME, CGI, HTML, CSS, etc) for onself: 'Someone else has already explored the space and memoized a set of solutions, so "use Them.pm"'.	[reply]
Re: Pedagogy: pointers or plaintext posts by tjh (Curate) on Apr 08, 2002 at 21:45 UTC
I've answered this from my perspective as a Perl user/middle-aged-student since it flowed easier on this topic. I've done a fair amount of teaching on other subjects, but thought I'd lay off the theoretical. I hate docs without sample code examples or snippets, or module documentation written mostly for someone above my level of understanding; I love finding code samples on PM that do something differently than I may have thought of (which happens often BTW) ; Also, a code sample may solve my current problem explicitly, but I'll be further along and more willing to dig in to use the module, or whatever, on my own next time. Plus, I study the code to be as sure as I can about why it works the way it does - I have to maintain it after all; Idomatic Perl usage isn't always obviously documented, and learning from senior Perl users always seems like an astounding opportunity for me.; Pointing me to 'the manual' is often not useful to me as I've almost certainly already been through them, but pointing me to other's writeups about the same issues has usually been worth its weight in gold; I dislike being flamed for not having read some write-up or non-official document somewhere that I never found, possibly because it was deep in a cultural abyss I wasn't familiar with. I also dislike posts of some Perl masters that flame (a little or a lot, and there's really only a surprising few in the Perl world who actually do 'flame on' very often) the poster for same, or for non-idiomatic usage not obviously documented, and don't give pointers/links to follow either. My sense is that most Perl users I read online do not have CS degrees, and their (our) depth of understanding is always more shallow than a master's. (Don't get me wrong tho - I've learned a lot from being flamed, and from reading the heat others recieved. I'm just not sure it's a hugely successful educational tool in a public, unfocused forum.) Thanks for asking about this. That you even thought to ask about it publicly, did so, and will get thoughtful answers here is a perfect example of the PM's value. The huge variety of answers on PM, as well as the approachability of most Perl documentation, books, FAQ's etc, and the unbelievable helpfulness of Monks is really remarkable.	[reply]
Re: Pedagogy: pointers or plaintext posts by danger (Priest) on Apr 08, 2002 at 20:35 UTC
You can lead a student to water but you can't make him Think! I don't think you are doing anyone a disservice by supplying code and explanations that either go beyond the documentation, or put the documentation into the context of the problem they are trying to address (which is what I think you usually do, and what I try to do when time permits). Some people, especially at first, find it hard to make the leap from the docs to their own problem space. If you supply both pointers and your additional helping hand approach, I don't think you are hurting anyone: Those who just need (or prefer) a pointer to the docs get one; those needing a little applied documentation transference also benefit --- and when/if they do read the docs, your additional demonstrations will probably help them further understand the docs. Those who blindly use your code without trying to understand are, well, ... blind by choice. Always remember, though, that this place is an archive --- just because you might suspect that the person asking isn't interested in reading the docs or learning doesn't mean that the next person with a similar question who happens across (or is pointed to) your post won't gain full benefit. Fuller explanations may seem wasted on some, but they are never really wasted.	[reply]
Re: Pedagogy: pointers or plaintext posts by cjf (Parson) on Apr 08, 2002 at 21:20 UTC
I thought your post at Re: CGI Design was an excellent reply. My main problem with posting code is that the person asking the question won't learn as much as if they read the relevant documentation, this was not the case with your reply. As you state, the docs for some things can be overwhelming at times. In order to prevent people from being scared off, it's important to specifically point them to what they need to read (oversimplified example - don't say 'read perldoc' say 'read perldoc -f map'). If you're willing to spend the time to provide them with the relevant information within your reply, as you did, that's even better. The combination of code specifically addressing their question and an explanation of what it does makes it even easier to learn from :).	[reply]
Re: Pedagogy: pointers or plaintext posts by emcs (Scribe) on Apr 09, 2002 at 04:10 UTC
Fellow Monks: As an old timer, who is a newbie coder (and a new initiate) I think that one reason many people never become proficient at writing perl is the abundance of scripts that are already out their, and are available to use. Speaking only for myself, I have always been able to patch scripts together, and to get something to work (but I never learned much) It has been my experience that the only way I have learned to do anything is to learn from my mistakes. What I have found most useful is a script that I copied from a book, to grep through the FAQ's for information. I find that 90 % of my errors are syntax related that are explained quite well, when I use 'warnings' and 'strict'. It is my belief that the best way for the expert coders at the monastry, to help newcomers, is to encourage them to just write code, with the help of a good book and the perl documentation. Reading books but not writing code does not work as I have already tried that; sometimes you just have to do it. Fortunately, I am getting to the point now that I can write short scripts that do not generate errors, but they will not do what I want them to do either. However, I am very pleased with this as I consider it progress. Perlmonks is a magnificent resource and an exceptional pool of talent. I consider myself fortunate to have found this site. emcs	[reply]
Re: Pedagogy: pointers or plaintext posts by belg4mit (Prior) on Apr 08, 2002 at 22:56 UTC
>But am I doing them a disservice? >If they blindly use my code snippets >without understanding, this is a bad thing. Isn't that what's referred to as cargo cult programming? My take is to do pointers(à la metadoktor, I include nodes here), and if the problem has been sufficiently explored or is interesting provide some code. This is what I like for people to do with me, and what I sought when I began. I am often slightly dismayed when I come to a node that asks a question relating to the fundamentals. The inquisitor has a chance to truly learn and a monk has succumbed to the temptation to post code, to solve the problem for them. Part of the reason it is good to refer people to documentation is that something other than what they are looking for may get lodged in their casava that they can fetch or have an inkling of use for later. This is why I read through the Camel etc. occasionally. It's also why I read the CPAN uploads for Modules that you want to know but haven't used yet. Then again, I also read the encyclopedia for my own amusement and edification. `-- perl -pe "s/\b;([mnst])/'\1/mg"`	[reply]
Re: Pedagogy: pointers or plaintext posts by trs80 (Priest) on Apr 08, 2002 at 20:53 UTC
Didn't we just go over this? here and my reponse here	[reply]
Re: Re: Pedagogy: pointers or plaintext posts by Ovid (Cardinal) on Apr 08, 2002 at 20:56 UTC
I checked the node and I see that I didn't vote on anything there, despite there being some good replies. That tells me that I never saw the post in the first place. Sigh. It seems like I can't think about something without someone else having thought about it first :) Cheers, Ovid Join the Perlmonks Setiathome Group or just click on the the link and check out our stats.	[reply]
Re: Re: Re: Pedagogy: pointers or plaintext posts by trs80 (Priest) on Apr 08, 2002 at 21:10 UTC
I ++'d yours though, it does have a slightly different skew to it, but it was odd that I was reading the Yahoo! Internet Life article on plagiarism when I saw your post :)	[reply]
Re: Pedagogy: pointers or plaintext posts by helgi (Hermit) on Apr 09, 2002 at 12:51 UTC
The docs invariably ( 99% of the time ) include a short snippet of simple code that implements a common task. This is usually far better than posting your own home grown hack. Regards, Helgi Briem	[reply]
A reply falls below the community's threshold of quality. You may see it by logging in.


Perl-Sensitive Sunglasses
	PerlMonks