Oh. Thanks a lot for the response! What's most disheartening, is that even for a person with your experience, the doc is overly complicated, and I of course too can relate to reading docs that are totally incomprehensible. What I can say in my defence, is that I absolutely didn't want to make the doc so that it appears aloof and to pose as if I have huge experience in functional programming, which I don't. What it shows rather, that I'm a lousy documentation writer, if even my best intentions turn into such a result.

In the long run, I know what to do. Learn to write better, write more, all the usual advices for the aspiring writers. However, that'd be really sorry NOT to rewrite this doc and leave it in the current state when it is hard to understand what it is about. I'll try to rephrase and remove "X like Y", thank you for the advice. And I'll definitely try to rewrite hard sections into simpler ones, but here's a question to you, as a writer: where is the acceptable level of simplification? It won't possibly be a good idea to explain functional programming tricks to make the reader fully appreciate the tricks IO::Lambda does. However, without referring to the concepts from the functional programming, a single paragraph can easily explode into twenty. Possibly that's not a bad thing though.

Also, I don't really understand what you mean by "make the docs more standalone". Is your idea to split the large document into smaller pods for readability?

Finally, thank you for using time on bringing up problems with the docs. But I shall need to ask you and everyone interested, I need your help with docs too. I didn't realize that until now, but apparently the documentation is the biggest showstopper. Would anyone like to write, or help me write a gentler introduction to the module? I'll help all I can.

In reply to Re^2: IO::Lambda: call for participation by dk
in thread IO::Lambda: call for participation by dk

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.