This could only too easily become a flame war, so I am replying once and
will not answer again unless it is about substance.
The Perl6 community is warm, generous, and intellectually inspiring.
Those virtues should be defended against unseemly and intemperate
language. Calling a documentation writer a 'jerk' is wrong.
On 03/10/18 07:40, ToddAndMargo wrote:
On 9/30/18 9:11 PM, Richard Hainsworth wrote:
But I thought you just implied you wanted pro stuff, not beginner stuff.
I have no idea how you got that out of what I said. I want the
beginners stuff included with the pro stuff.
Yes the best of all worlds, and it must be short. Demand the impossible
and complain when it does not happen. There are a number of people
trying very hard to balance the contradictions of writing documentation.
We need to support them and offer constructive suggestions. Clearly my
post was wrong because you did not *think* about what I said, only
reacted negatively to my British sense of humour.
So what is wanted is 'common user' stuff (see below).
You are mixing socialist political terms with what I
am stating. By "common user" I mean a typical user.
The term was meant to differentiate typical users from
experts.
Where did 'socialist' come from? You said 'common user' and I was trying
to elicit from you what it meant. But as it happens I do not think that
'socialist' is a negative word, and for many people it means an emphasis
on society and community (as in this very valuable Perl6 community)
rather than on solitary individuals.
Actually, I do not understand what you are saying at all, eg., 'I
have know how to use ...' is not clear.
Again, I have no idea how you got that out of what I said.
I quoted your words from your post. They are in quotes. Your use of
English grammar is not standard, and consequently it is ambiguous.
When I use a function all the time, I know who to use the
you know 'who to use' or 'how to use'? It would be useful for you to
read what you have written for mistakes before clicking on the 'send'
button. That way, other people can understand you better.
function. The problem was that I could not reverse engineer
the documentation.
In other words, I figured out how to
use the function from other sources than the documentation.
Had I used the documentation, I never would have figured it out.
That is the issue.
This use of 'reverse engineer' is obscure. But if you mean that you had
to read around a bit in order to understand, I suggest that this is
quite a normal intellectual activity. That is why repeatedly it has been
suggested that you read a book.
But I am confused about what *you* want from the reference
documentation.
I think maybe there is a translation issue between your native
language and mine. I have been very clear what I am
after, so I won't repeat it yet again.
My native language is English. I was born to English parents, went to
school in Leeds, went to University in London, studied computer science
and economics in Birmingham, spent 20 years editing and translating into
English from Russian in Moscow. I speak and write Russian, and I am
learning Cantonese.
I do get it: you are following the example of the current crop of
political leaders in the US. When someone demonstrates - as I did in the
previous post, and in this one - that your English grammar and spelling
are slovenly, you throw back the criticism as if I am guilty of the
same, and charge that my native language is not English.
So no it is not a translation issue. What you want is not clear because
(a) you do not write clearly, (b) you ask for different things at
different times, (c) you assume that the world is predominantly the same
as you, when it is not.
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.
You are again missing the point. It is wonderful if the writer
wants to share an interesting, complex way of doing things.
But only AFTER he explains it in is simple terms. You don't
share a calculus equation with someone until after you
teach them the fundamentals of arithmetic.
I did not miss the point. You deleted the part of my response where I
agreed that there should be simple examples. You also deleted the part
where I pointed out that calling someone a 'jerk' is not polite. It is
possible to get carried away by beauty and elegance and forget the need
to start with simple things. That might make the explanation cryptic; it
does not make them a jerk.
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?
You are mixing socialist political terms with what
I am saying again.
Where did socialism or politics come from? Is this some sort of insult?
The term 'common user' is yours. I asked if we could expect a 'common
user' to have read an introduction.
You may not be aware, since you do not learn from reading books (you
said it, this is not an inference or insult), but when an author or
writer sets out to write something, there has to be effort to define the
intended audience. That is why there are children's books, and reference
books, and dictionaries, and so on. You are saying that this
documentation should be for the 'common user', so what is that?
Perl 5's perldoc did a wonderful job of this.
I never liked perldoc. 'To whom how', as they say in Russian.
I find perldocs from the command line a total pain in the butt.
Fortunately, it is repeated on web beautifully.
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. ;)
I think that there is a translation and maybe a cultural difference
that has lead you to misconstrue my statements. That or you are
just trying to pick a fight. Your "buffoon in the White House"
statement is definitely trying to pick a fight.
Actually, I was using British humour to show that you had not spelled
the word correctly. The participle form of the verb 'gripe' is 'griping'
- if you were to have used a dictionary of the English language before
sending your post, you would have discovered this. The particle form of
the verb 'grip' is 'gripping'. You said in your post, which you cite,
'instead of constantly gripping about the problem'. It is clear you
meant 'griping'. No translation problem on my part, just a spelling
problem elsewhere. Or perhaps a problem in using a dictionary?
Like I said at the beginning, I will not respond again if the response
is an 'ad hominem'.
The reason I justify this response is (a) intemperate and insulting
language would erode the value of this community if allowed to go
without response, (b) there are substantial questions to be faced in
writing documentation, which should not be overlooked because they are
raised in an intemperate manner. I do believe that the Perl6
documentation is going in the right direction, and I find it mostly
useful. I know from the interaction on this Forum that there is a
willingness and desire to improve.
It seems to me that the documentation needs to accomplish several
contradictory things, and because they are contradictory, there will
always be an opinion about how to do better. These contradictions are -
I think and in line with what the docs themselves say - as follows:
- being concise, whilst being comprehensive
- finding a balance between terminology that is specific to Perl6 (eg.
signatures), which should be known to the intended user, and making
explanations understandable to someone who has not yet entirely
comprehended the whole of the language
-- This is a real problem. All programmers know functions transfer data,
and in most languages this is indicated using parameters in brackets
after the function name. But I expect many experienced programmers will
not appreciate the extra information being conveyed in signatures in the
Perl6 documentation, and how to unpack it.
-- My suggestion would be to enhance the introduction to point to
specific chapters/sections that are crucial to understanding the whole.
The current section 'about the docs' does not quite do this. Perhaps
there should be a section called 'how to use the docs'?
- using examples that illustrate a topic as simply as possible, yet also
including examples that show how expressive some language component can
be when combined idiomatically with other components of the language. In
a sense this is very similar to dictionaries that illustrate a word as
used by well-known authors and stylists. The choice of sentences is a
part of the art of dictionary compilation.
- finding a way to cross-reference components of the language, to aid
someone find the answer to a question that may be vaguely formulated.
-- I think that the current docs do this very well. The search tool
works well. But sometimes, I do not remember exactly what to look for,
and I have to try several keywords to hit on the right one. Some form of
context-sensitive help would be useful, but this is - I recognise - a
non-trivial task.
Richard
aka finanalyst
