Todd,
I've already added to this conversation given that your 'perl' box was
corrupted. But when I read this post last week, I felt it needed some
response.
You actually have touched on some deep issues. Please allow for some
humour below.
<snip>
First off, courses, beginners books, and the likes, do not work for me.
So you do not want to read beginners' stuff, just the stuff real pros want.
What does work is just code what my customers and I need. And a lot of
what do is to Read The Freakin' Manual (RTFM, now-a-days called "just
Google it").
Read the manual. Got it. I do that a lot for many languages, eg. php,
css, html. Actually, the manuals for css and html are bloody awful. Much
better are tutorial sites. So the problem of documenting something
complex in a balanced way is not unique to perl6, and it is a deep issue.
The Perl 6 routine's documentation is written as a refresher to
those how already know what they are doing, and as such is
pretty useless to common users seeking wisdom.
But I thought you just implied you wanted pro stuff, not beginner stuff.
So what is wanted is 'common user' stuff (see below).
Why even post
it to the general public? The design specifications and
not posted (except if you Google them).
This is a misrepresentation of reality. Larry wrote about the
'whirlpool' rather than 'waterfall' concept of development. Perl6 was
not written to specs, rather the specs and the language and the tests
(considered a part of the specs) have co-evolved. There is a link to
them on the main perl6.org page, but the documents are historical, not
prescriptive. And so the links to them are not given prominence, so as
not to confuse the commoner, as it were.
*** I am not after the manual to teach me how to use Perl. ***
Well I agree, if you want beginner stuff to learn, first read a book.
In several instances, I have know how to use functions and looked
backwards in the manual to see if there were any other bits
I could use. I COULD NOT REVERSE ENGINEER the manual
EVEN THOUGH I completely understood how to use the function.
This is bad. Really bad.
Actually, I do not understand what you are saying at all, eg., 'I have
know how to use ...' is not clear. Do you already know about some
'functions' and want to know more, or do you need to know about a
function? Even though you SHOUTED at us, I do not know what you mean by
'reverse engineer the manual'. So I cannot fathom why not being able to
do so is bad.
This is what I am after:
The manual should be written like a spoken language dictionary.
First 'should' is subjective to you. It is not imperative to those who
contribute. It *is* a part of the process of writing the documentation
to evolve a style and a terminology to accomplish several
self-contradictory things, eg., brevity and comprehensiveness. The
balance is not easy to accomplish, and we all want something better.
This is a deep issue. There is no single answer for everyone.
1) it should tell you what that word is
Everyone would agree with this point. Frankly, having read the
documentation for other software, the perl6 docs succeed very well.
However, I think your problem is that you don't like the terminology
that is being developed by perl6 documentation contributors (part of
the deep issue).
But all spoken language dictionaries (I looked up 'if' and 'as' on
Websters, Collins, and Oxford dictionary sites) have terminology and
special signs for pronunciation, or for grammatical function, eg.,
pronoun, conjunction, adverb. To understand a dictionary, you have to
learn about the terminology.
If you look up words for other spoken languages, eg., Cantonese, then
you get things like sentential particles or classifiers, neither of
which exist in English. (A bit like the difference between perl6 and
perl5). This means that you actually have to know something about a
language before being able to use the dictionary, and dictionaries for
different languages are, well, different.
2) show you how to use it in context.
No quibble here. But perl6 documentation does provide examples. I would
agree that there should often be more. Contributions are welcome. As
programmers work through different contexts, they come up with
interesting examples. I don't think anyone has rejected new examples.
And I might point out that a dictionary is not a HOW TO
book to teach you the language.
We all agree. There is a difference between reference documentation and
tutorials. The problem is that it is difficult to discern from your own
explanations (even this very post) what it is you want. And given my
experience in other languages, sometimes tutorials are good, sometimes
manuals are good. Often `stackoverflow` is the best goto. There is not a
single experience. Personally for perl6, the docs are the best.
But I am confused about what *you* want from the reference documentation.
3) when calling other term to explain things, it should
pick the easiest term available. It should not pick
any nasty, advanced terms. (Unless the writer enjoys
confusing the reader and bragging about how smart
he is. And he is a jerk.)
This does not seem to be correct English. However, by squinting at what
you wrote, I think I agree with you that some of the explanations or
examples are cryptic. I think that the people who wrote them sometimes
want to show off the elegance and expressive beauty of perl6 (that is a
nicer explanation than assuming they are jerks). Often I am inspired by
these examples. Sometimes, I despair because I am trying to 'grok' one
thing, but the examples expect me to have 'grokked' another, which I
haven't. When this happens, I have tried to ameliorate things with a
contribution.
4) It can reference advanced topic or follow on topics
but keep them out of the topic. Dictionaries do this
all the time. "See such and such"
I entirely agree. And yet I am reminded of a poster (I wonder who???)
who seemed to want an explanation of 0-based counting in the definition
of a string function ..... The community response was much in line with
this precept.
5) leave the common user knowing how to use the topic,
not wonder if the writer writes manuals for the
IRS in his spare time.
We come again to this category: 'the common user'. This person (possibly
there are more) is not a 'beginner' nor a 'pro'. What is to be expected
of a 'common user' of perl6? Can we assume that a 'common user' has read
an introduction to perl6?
I could have asked if a 'common user' is like the buffoon in the White
House who has such a big brain that he doesn't need to read, or take
advice from anyone, and who created an international precedent by being
laughed at by UN diplomats for speaking like he was talking to a
like-minded crowd, but ....
... I won't because that would be off-topic, and political, and I
certainly would not want to upset anyone from the exceptional country.
Perl 5's perldoc did a wonderful job of this.
I never liked perldoc. 'To whom how', as they say in Russian.
I have been posting RFE about this as they come up.
So I am trying to be part of the solution instead
of constantly gripping about the problem.
Indeed this discussion has, at times, been gripping, but I hope you
don't think I have been griping. ;)
-T
