On 2019-12-09 12:31, Philip Hazelden wrote:
On Mon, Dec 9, 2019 at 1:47 AM ToddAndMargo via perl6-users
<perl6-us...@perl.org <mailto:perl6-us...@perl.org>> wrote:
Hi Phillip,
Have you ever been to an IEEE seminar and attended a lecture
on a subject that you have intimate knowledge on hoping
to pick up some additional tips. In the lecture you keep
shaking your head saying to yourself "What, Huh? What
the Heck?". After the lecture you ask yourself why you
wasted both your time and your money? And here is the thing,
They are doing exactly what you stated are "cleanly and precisely" done.
This is important: they really, really aren't.
You've offered me a hypothetical in which someone discusses a subject
that I'm expert in, and I leave confused. In actuality, what happened is
that I read some text on a subject that I'm no expert in, and I found it
plainly clear. The difference between "confusing, even to experts" and
"not confusing, even to non-experts" is profound.
One thing that these situations do have in common is that to a newcomer,
both situations may be confusing. They would be confused by the
hypothetical because in the hypothetical, the discussion is genuinely
confusing. And they may be confused by the actual text, because they may
lack the background to understand it, even though it's not confusing to
someone who does have that background. So although there's a profound
difference between the two situations, a newcomer may experience them
the same, and may have no way to distinguish the genuinely-confusing
from the merely above-their-level.
(After all, for someone to reliably predict how an expert would react in
a situation, they must be able to apply the knowledge and experience of
an expert. If someone were to say: "well, if I knew more than I know
now, I would think X; but at my actual current knowledge level, I think
Y"... that person would sound very confused.)
You refer to yourself as a newbie. And you have repeatedly said that for
something to be IEEE-ese, it must be confusing not just to newcomers,
but confusing to experts.
And so I ask: given that you are not an expert, what makes you think you
can tell the difference between IEEE-ese and and something that merely
happens to confuse you? How do you distinguish the genuinely-confusing
from the above-your-level, given that you admit to not having reached
expert level?
If you say that the documentation is confusing to you, I will accept
this without question; you are probably the world's leading expert on
what is confusing to you, and I have no reason to disbelieve you. If you
say that the documentation is confusing to other newcomers, I may be
inclined to trust your judgment.
But you repeatedly accuse the Raku documentation of being confusing to
experts. (You accuse it of being IEEE-ese, and you define IEEE-ese as
confusing to experts.) I do not trust your judgment on that matter. If
you think I should, I invite you to say why.
Do you see ANYONE on this mailing list, other than
me asking how to untangle "method contains(Cool:D: |c)",
even though they are "cleanly and precisely" done?
(Well most of the time.)
Indeed, I do not.
To me, this state of affairs suggests that although the documentation is
confusing to you, it is not confusing to others; thus, not IEEE-ese.
Or they are ignoring them and going elsewhere.
Perhaps to you, this state of affairs suggests something different. If
so, I can't think what that would be.
Hi Philip,
You make some interesting points. What you missed exposing
was the presentation of the teaching.
Have you seen any of Larry's responses on this group? He
takes complex subject apart and makes then extremely to understand. He
targets who he is speaking to. He is
extremely talented at it.
Now those IEEE lectures I wasted money on, I was as much
of an expert, if not more so, then the presenter. Their
presentations stunk. I could not figure out heads from
tails. The information was peer reviewed, absolutely
accurate, and completely useless -- also know as
"IEEE-eese". IEEE-eese seeks to confuse, not to
communicate. IEEE is known for it. You quickly
learn to go elsewhere for information. So again,
this is back to the way the information is presented.
Let delve into an example from another field.
You are trying to document how to use a cell phone.
Would describing the specification of the internal
processor be appropriate? Yes and no.
"Yes", if your target audience were fellow engineers.
"No", if it was the user.
This is about determining your target audience.
Now back to Raku.
Take a look at
https://github.com/rakudo/rakudo/commit/696eea2de6e67135b3b574ecb579ede16045ede6
This is where the incorrect information presented on
the Docs for .contains is being corrected (among
other things). The commit is a fascinating insight
into how the developers are doing their thing.
As a BS in Electrical and Computer Engineering
and a sometimes programmer, it was a wild ride
to witness. Did I understand all of it. No. I am
not a developer. It was still fun to read.
And this is the method the developers use to specify
things to each other. And it OBVIOUSLY works well
for them as the end result of Raku is spectacular.
I LOVE Raku.
Now back to the presentation of the information in
the docs. It borrows from how the developers talk
talk to each other. This is not how you talk
to users (Rakoons) any more than me telling you
how may gates were in your cell phone processor
is appropriate to how to use a cell phone.
So again, what is the target audience?
Ask your self, do you or I really need to know
how the developers create the code to understand
how to use it? Obviously not and it would
only cause confusion.
The Docs, need to change this culture, which is to
give developer level information (number of gate in the
CPU) as a teaching tool for those that only need to
know how to "use" Raku. Saying "to understand how
to use Raku, you first have to understand how the
developers communicate with each other" is ridiculous.
You don't need to know how processors work to use
a cell phone.
For the Docs to be useful to Rakoons, the developer
level information needs to be removed. In its place:
1) This is what the function does.
2) This is how to use it.
This is all about technical writing. Addressing the
wrong audience makes the information next to useless,
(not to mention all the mistakes in it). Not completely
useless, sometimes an example will sneak through that
is helpful.
You do not need to know the mechanisms the developers
use to develop Raku to program in it any more than
you need to know the die size of the processor in
your cell phone to use your cell phone.
Thank you for your forbearance.
-T
