On 2019-12-06 01:24, Laurent Rosenfeld via perl6-users wrote:
Manual pages (which are reference material) and tutorials are two very
different kinds of writing. Manual pages are usually more difficult to
understand than (good) tutorials, because they have to be *very
accurate* and as complete as possible (if not exhaustive), while
tutorials can leave out some intricacies or gory details.
Hi Laurent,
Definition: IEEE-eese
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.
I have uncovered several booboos in the docs. I find them
to not be all that accurate either. I really don't trust
them. And since they are written in IEEE-eese, booboos are
really hard to spot.
And guys like me are the perfect ones to spot such booboos
as we don't know what to expect and don't think we see what
we see. IEEE-eese put a clamp on that.
And when I do spot them, it is really hard to get a fix
past the bug reporter's guard dog. You have to argue and
argue and argue. I don't report a lot of bugs to them
anymore do to this. It is far more effective to report
them here.
Have you seen perldocs for Perl 5? They contain everything
a developer would need and a wonderful explanation for
the rest of us to use, EVEN ME. They are beautifully
written. Perl 5's docs wipe Perl 6's docs faces.
I apologize if I offend anyone, but Perl 6's docs stink.
They need to be readable by both developers and users
alike. They are obviously not. Perl 5's docs prove this
is possible.
And by the way, the developers have their own set of
specifications. There is no excuse for writing the Perl
6 docs in IEEE-eese.
-T
