On 2019-12-07 08:17, Philip Hazelden wrote:
This is not IEEE-ese. Earlier, you defined IEEE-ese as
Technical written material that uses so many obscure
terms and unnecessary technical jargon mixed with
deliberate obscurities that even a reader with
intimate knowledge of the subject are confused.
Example: read any published paper from IEEE.
That is, IEEE-ese uses technical jargon *unnecessarily*. By contrast,
what you quoted is simply using technical jargon *clearly and
precisely*. (It does have a typo, the word "to" is missing between
"invocant" and "Str"; and "Str.contains" links to the wrong anchor in
the page.) It can probably be hard to tell the difference, if you aren't
familiar with the technical jargon in question. But in this case, if you
know what an "invocant" is, and what it means to "coerce" something, and
to "call" a method, then the meaning is clear; and in fact, the way it
was written seems like the obvious way to write it.
If you don't know what those words mean, then the meaning won't be
clear. (But even then, clicking the link on "Str.contains" and glancing
down that page a little should give you some hints.) Perhaps, to make it
easier for you to understand, the docs could stop using words like
"invocant" and "coerce". But that makes it *harder* for people who do
understand these words, because those people then have to read more
words and translate them into their precise understanding.
Perhaps it can be rewritten to make it clearer for people who don't know
the jargon while not losing concision or expressiveness for people who
do. But that's not necessarily an easy thing to do; and someone who
doesn't know the jargon is unlikely to do it well.
As for `|c`, that's part of the type signature. For people who can read
type signatures, glancing at the type signature of a method can be much
easier than reading a possible-imprecise description of how to use it.
If you can't read type signatures, you're out of luck; but that's no
reason to hide them from people who can. If you type `|` into the search
box, there's an entry under "Reference" named "| (parameter)" (which
admittedly also links to the wrong anchor in the page), and another
under "Syntax" simply named "|", and either one of those will (with
perhaps a bit more reading and following links) take you to
https://docs.raku.org/type/Signature#Capture_parameters which describes
what it does.
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.
These lecture are painstakingly peer
reviewed. So why can't you figure out what the heck is
going on and you KNOW THE SUBJECT? This is IEEE-eese.
Now back to "contains". "method contains(Cool:D: |c)"
is not correct. It is missing the "$pos --> Bool" which
tells you the result of the method. (Hidden by the
IEEE-eese and "is intuitively obvious and left up
to the student to figure out for himself.")
But for the purpose of the rest of my letter, lets say it is
correct.
Okay here goes. In technical writing, there are usually three
different targets for your audience.
1) your peers. A civil Engineer to another civil engineer.
In your case other advanced developer level folks.
2) to someone is a parallel field. A mechanical engineer to
an electrical engineer. A Raku programmer to a C++ programmer.
(I do talk to C and C++ programmers on occasion. They are great with
explaining system calls)
3) to those either new to the field or outside the field, general public
so to speak. An allopath explaining an
injury to a patient. In your case, explaining how a Raku
function works to me, as I am a beginner.
So, you have to ask, which one of the three were these
documents in general and "method contains(Cool:D: |c)"
in specific targets at?
1) follow developers and advanced users that don't need
them and have their own spec's?
2) to someone in a parallel programming field? They
will never figure them out and just ignore them
and think you are a nut.
3) to newbies, such as myself. Or even refreshers
to regular users? They can't understand them.
This is where the documentation falls on its face.
The TARGET audience need to be 3 above not 1.
Perl5's Perldocs actually manages to both target
both 1, 2 and 3 above.
Ask yourself, do you see ANY tutorial on Raku that uses
the "method contains(Cool:D: |c)" jargon and explains
them? Do you see ANYONE EVER using "method contains
(Cool:D: |c)" to explain things EVER?
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.)
The times I have asked this group to untangle the
"cleanly and precisely" documentation, Larry Wall
himself has had to jump in and help.
So, if you are going to use this method of documentation,
you need to take it apart and explain every little detail.
I have 190 keepers like the "Hashes" one I posted here.
Take a look at what I did with "contains". It cuts
through the IEEE-eese and give the reader (me) what he
need to know. And the Target is not a developer or
a someone in a parallel field. It targets actually
users of "contains", like me. And reading through it,
do you see ANYONE else trying to take apart and
explain the IEEE-eese in the documentation?
I will post my "Contains" in a new thread so other
may use it.
To summarize. What is the target audience?
-T
