Rewrite the example so that it has no wombles

AlexDaniel commented 8 years ago

Motivated by https://github.com/perl6/doc/pull/567.

     class Womble {}
     class GreatUncleBulgaria is Womble {}
     my $womble = GreatUncleBulgaria.new;

     isa-ok $womble, Womble, "Great Uncle Bulgaria is a womble";
     isa-ok $womble, 'Womble';     # equivalent

Originally the pull request suggested to add a link to wikipedia. Let's just rewrite this example so that it does not need any explanation.

labster commented 8 years ago

Please explain why this example needs explanation. When I read it the first time, my brain translated that Womble to Foo and GreatUncleBulgaria to Bar, and it makes perfect sense to me. Then I looked it up, because "womble" is a funny word, but it doesn't hamper understanding of the Perl 6 language. I don't like boring docs, and I don't like people explaining jokes as if they're afraid of themselves.

zoffixznet commented 8 years ago

When I read it the first time, my brain translated that Womble to Foo and GreatUncleBulgaria to Bar, and it makes perfect sense to me.

+1 on keeping example as is. Womble is a funny word and I didn't even care to look it up. The example is clear without knowing its meaning.

AlexDaniel commented 8 years ago

OK

jsoref commented 8 years ago

My brain choked when I ran into Womble. I had no idea what it was.

If your brain translated it to Foo/Bar, why not do everyone else the favor of just rewriting it to Foo/Bar?

zoffixznet commented 8 years ago

Because Wombles is a funny word and makes docs less dry to read :)

We can definitely make a change if there are enough votes. So far there are 2 for keeping it, 2 for changing it. We need a tiebreaker vote :)

stmuk commented 8 years ago

I don't think this should be changed.

I like the Wombles example and anyone curious to what a Womble is can google it and discover in a few seconds.

coke commented 8 years ago

👎 from me, no reason to remove the wombles. I have no idea what they are, but it's fine. As long as it's not some oblique inappropriate reference, don't care.

jonathanstowe commented 8 years ago

I'm in the leave the Wombles without further explanation camp, it's a slippery slope to having pages about "foo"/"bar"/"baz", "Bob" and "Alice", "Barbie" and "Ken" and all sorts of allusions that are made to culture outside the documents.

raiph commented 8 years ago

TL;DR I suspect that, in an example that's supposed to allow the reader to focus on how test functions work, even if it is isa-ok, inserting several unknowns and a non-obvious singleton for no compelling reason is LTA.

foo (and bar when it's used alongside foo) abstracts from all grammatical categories.
Unless at the start of a sentence, Foo or Bar (i.e. capitalized) generally implies a noun that denotes a class of things or a noun that denotes a particular thing.
alice/bob/Alice/Bob (regardless of capitalization) imply a noun denoting a particular thing.
If someone doesn't know what Womble is, the capitalization suggests a noun that's either a class of things or a particular thing whereas the phrasing GreatUncleBulgaria is Womble, which uses is rather than isa, suggests Womble is (being used as) an adjective.
class GreatUncleBulgaria strongly suggests GreatUncleBulgaria is a class of things.
GreatUncleBulgaria includes words with existing English denotations. If one recognizes some or all of these words one might think it represents a class of countries (Bulgarias, specifically the GreatUncle ones) or a class of people (Bulgarian Great Uncles). However, I find myself more inclined to think it implies a single particular thing (a particular person or a particular country). I suspect that's partly due to how Great Uncle and Bulgaria tend to be used in practice and partly because the wombles were part of my childhood.
my $womble = GreatUncleBulgaria.new suggests $womble is assigned an instance of a GreatUncleBulgaria.
The isa-ok $womble, Womble, "Great Uncle Bulgaria is a womble"; implies that Great Uncle Bulgaria is a particular thing (a particular person or particular country).

From all of this one can conclude that the GreatUncleBulgaria class is almost certainly just for creation of a singleton whereas the Womble class is even more likely not.

This is all logical but seems unnecessarily complex. Perhaps it's me bringing the complexity but I suspect not.

shadowcat-mst commented 8 years ago

The original commit used the wikipedia URL (after discussion on IRC that presumably @AlexDaniel missed) instead of removing it because (1) these are awesome names (2) the Wombles are awesome (3) this is perl6, and if you're offended by having a sense of whimsy then you can go join the people complaining about camelia over there in the far corner.

Oh, and (4) "making good use of the things that we find, things that the everyday folks leave behind" (from the theme song) seems epically perlish to me.

jsoref commented 8 years ago

@shadowcat-mst : Well, I wouldn't say they were (1)/(2) awesome.

But, it was an attempt to avoid trampling a (3) spirit which might be acceptable/wanted, while enabling others to have a chance of figuring things out.

@raiph does a good job of parsing the problems in the text. It's too complicated w/o some assistance, and not only is it too complicated, you're liable to be sent down the wrong path, which is the worst kind of documentation.

jonathanstowe commented 8 years ago

I'm guessing that all the rest of the documentation is finished then if this is really the only thing that people are worrying about.

AlexDaniel commented 8 years ago

Butterflies are awesome. Camelia is awesome as well.

End of bikeshedding. I hope everyone is happy now.

AlexDaniel commented 8 years ago

Reopening since @stmuk wants a consensus on changing the example to an obviously better one.

coke commented 8 years ago

With the original example restored, this is fine to close now, IMO.

zoffixznet commented 8 years ago

Reopening since @stmuk wants a consensus on changing the example to an obviously better one.

I think we've reached that already. There were 5 votes for keeping Wombles and 3 votes for changing to something else. I'm not entirely sure which side mst voted for, if any, but even if their vote is to be tallied for the changing side, the keep side still wins.

I think there are far more important documentation issues everyone can focus on instead of this, so I'm closing this on the grounds that the issue was resolved by popular vote. I hope we can agree that's a fair judgement.

paultcochrane commented 8 years ago

As the author of the Womble examples I thought my 2c might help, if only to provide historical context (I do not wish for the ticket to be reopened!).

I agree with @raiph: the examples are more complex than necessary, and it is a good point about the singleton aspect; @jsoref's comment about the docs being misleading is a good one too: documentation should not be misleading; the Womble examples were not intended to mislead, unfortunately they became weak illustrations of the relevant concepts.

The examples were written somewhat whimsically (not necessarily a bad thing), and the awesomeness of Wombles -- as happens with popular culture references -- is a matter of opinion. They were added at a time when there was no documentation about testing in Perl6 and were added so that at least something existed, with a view that it would be modified/improved in the future (which the docs have done so greatly since then, aweseome stuff!). While writing these docs, I had noticed that the examples didn't really flow naturally, however at the time I couldn't pin-point what was wrong, nor was I able to fix it, which I regret, nevertheless something was better than nothing.

I guess what I'm trying to say is this: I feel that the technical aspects of the Womble examples should be improved, however that the whimsical nature should be maintained. It is nice to see the Wombles being retained as per @stmuk's revert, however the complexity in the examples needs to be reduced so as to improve their quality irrespective of the reader's Womble-knowledge.

labster commented 8 years ago

I had thought of other examples. class Luke is Jedi. class Camelia is Lepidoptera. class Clarus is Dogcow. Not sure that they improve things, though. I feel like if you can't parse abstract symbols when looking at documentation, maybe we can't help you? Docs are all abstract symbols, in a sense.

@paultcochrane I get what you're saying, but I'm not sure what you want by improvement. Thematic harmony? That's probably one of the strengths of perl6/specs design docs -- large sections tended to be written by one person.

raiph commented 8 years ago

(+1 to keeping this issue closed, keeping whimsy in Perl 6, and welcoming wombles in particular.)

@labster What about the rule of thumb that class ThisIsAClass examples make sure that ThisIsAClass represents a class of things? This would rule out classes of specific individual things, eg class Great Uncle Bulgaria... and likewise for Luke, Camelia, Clarus, and perhaps even Dogcow. (The only exception I can think of right now is when discussing singleton objects.)

finanalyst commented 8 years ago

I'm coming to this conversation late. I'm FOR keeping wombles and every other whimsy there is. Foobar is in itself a whimsy. Clean context-free unimaginative single-function documentation sends me to sleep. I agree the testing example needs to be enhanced. Indeed a rich environment as the wombles allows for all sorts of extension. Personally I would really appreciate a long tutorial on testing Richard

Sent from my Samsung Galaxy smartphone. -------- Original message --------From: Zoffix Znet notifications@github.com Date: 10/06/2016 12:24 (GMT+00:00) To: perl6/doc doc@noreply.github.com Subject: Re: [perl6/doc] Rewrite the example so that it has no wombles (#577) Because Wombles is a funny word :)

We can definitely make a change if there enough votea. So far there are 2 for keeping it, 2 for changing it. We need a tiebreaker vote :)

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

Raku / doc

Rewrite the example so that it has no wombles #577