I feel that ToddAndMargo are only capable of "magical programming". I call that "magical", because people who program this way, only work with remembering from what they put into something, and what came out, *without* attempting to build a mental image of *how* the damn thing works.
The result is a continuously growing list of incantations that vaguely cover what they need from a programming language. This is fine as long as the programs or the documentation they write, does not have to be used by anybody else who is not using the "magical programming" approach. I would argue that *if* you want to become fluent in a programming language, you try to build a mental image on *how* that language works. Because, even though it will need refining, it saves you *so much* on what you need to remember! An example: remembering that you need to put in a piece of metal into a door and turn it to get in, versus the concept of a "key" that you need to gain access. > On 11 Dec 2019, at 00:02, Laurent Rosenfeld via perl6-users > <perl6-us...@perl.org> wrote: > > You've made a very interesting point on how difficult it is to write proper > documentation. I hope that Todd will reflect on that. > > > > Le mar. 10 déc. 2019 à 23:45, Rocco Caputo <rcap...@pobox.com> a écrit : > On Dec 10, 2019, at 15:35, ToddAndMargo via perl6-users > <perl6-us...@perl.org> wrote: > >> A method is a routine that you feed: Str.foo. > > It seems that you're saying the difference between a method and other kinds > of routines is that methods are "fed" something? > > The only thing I can think of that routines are fed are parameters. So it > seems that you're saying methods must have parameters, and conversely, > routines without parameters must not be methods. > > But that method invocation doesn't have parameters. By your definition, foo > is not a method. > > I know what routines and methods are, and I know what feeding is in the > transitive sense, and what you just wrote doesn't seem to describe a method > call (or its difference from other function calls). > > You seem to be describing technical things with metaphor. Precision is > important. Without it you run a significant risk of being misunderstood > unless the reader shares your particular frame of reference. > >> Think of "contains" as looking for a Needle in a Haystack. >> You feed contains data and what you are lookig for. In >> return is tells you True or False >> >> say "abc".contains( "a" ); >> True > > So you want "feed" to mean both passing parameters and supplying an invocant? > > You could just have said so. Something like "A method is a routine called on > an object." I can see why you'd want to use metaphor to spice that up. It's > silly, if not tedious, if not completely pointless to restate common OO > knowledge everywhere you intend to use OO. > >> Case insensitive contains: >> Note: "fc" converts you to lower case. It also converts weird charters to >> something on your keyboard > > I can't use this as documentation. "something on [my] keyboard" is too > imprecise (what language is my keyboard?). I'll need to consult the > technical documentation to understand "fc" well enough to actually use it. > Even worse, I suspect "fc" is some kind of mnemonic, and I'd probably have > understood it better if the expanded term was mentioned. > > It seems like using and documenting "fc" adds extraneous details and > distracts from what this article intends to discuss. Splitting it into two > articles with better focus in each would probably be an improvement. > >> "Str" >> is the string data (Haystack) that will be operated on by the method >> (contains) > > "data" is wasted everywhere you've used it. You should consider removing it. > > ""is the string that will be searched by the 'contains' method" is better > without "data" and possibly without "(Haystack)". > > Your personal note is probably fine since you know what you meant when you > wrote it. As documentation for a general audience, I'd say it's badly > written and needs significant edits. You should totally self-publish it > anyway. Probably in a public repository so that interested people will help > you improve it. > > -- > Rocco Caputo <rcap...@pobox.com>
