Very mature response to an otherwise insulting response. ++you.

The problem I have with any documentation is the case when I am presented with an example, but I have no knowledge of why I would need to understand that example, let alone if that example is even relevant to my needs. While I fully realize that the author can in no way be held responsible for being able to explain module usage to 100% of their readers -- you have to ask yourself at all times ... does this example make sense by itself?

And yes, it's OK if it doesn't.

But what if you can make it easier to understand anyways? What if you could write examples that progressively build up to them first. That is, don't introduce new concepts in the code snippet ... explain what the purpose is first. Here, take this quote from your docs:
Additional functions may be imported as usual by including them as arguments to use. For example: 
  use Class::InsideOut qw( register public );
 
  public name => my %name;
 
  sub new { register( shift ) }

[download]
OK ... so I see that I can import functions into my class. But what do register and public mean? You say "that is not important right now, I will explain those later." Except you are not here to tell me that. Instead I now stop, and waste brain cells wondering when and why I would need to alter my constructor to use register.

Instead, I would have only used one line: 

use Class::InsideOut qw( register public );

[download]
Don't show the usage for register and public until it is time to talk about them.

Another point -- your module seems to imply that the user needs to learn a new language subset, for example: 
  public   name => my %name;
  readonly ssn  => my %ssn;
  private  age  => my %age;


  $name{ refaddr $self } = "James";
  $ssn { id      $self } = 123456789;
  $age { id      $self } = 32;

[download]
Instead of throwing these cryptic and seemingly unusable code snippets at the learner, maybe you should instead teach them the language first? "Hey?!? How come I don't gotta stick a comma between readonly and ssn?" :/

While I do not agree with Herkum's tact, I must confess that the docs are a bit daunting. I must also confess that I am not a supporter of Inside Out Objects, and have not bothered to read Damian's writings on them. If I had, perhaps your docs would seem more intuitive to me, but if your ulterior motive is to attract users -- you gotta dumb it down sell it man. :)

In reply to Re^5: Simple question about Inside-Out objects by Anonymous Monk
in thread Simple question about Inside-Out objects by blazar

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.