Random comments/advice. Hopefully vaguely constructive:

• You don't actually say what your module does anywhere in the introduction :-)
• Stick to something close to the POD outline structure generated by h2xs, Module::Starter and similar. In particular:
  1. The NAME section should give a one line summary of what the module does
  2. The SYNOPSIS section should give a short end-to-end code example of the module working. Use comments to explain what's happening.
  3. The DESCRIPTION should supply a brief text description of what the module does
  Basically - if I don't have a good idea of what a module does by the second paragraph of the description I usually stop reading.
• Code beats text. Don't talk about concepts if you can demonstrate them with code. Currently you have to read about half the document before you get something close to a real-world code example.
• Aim the main module documentation at a reader who understands the concepts involved. If you need to teach or preach move it to separate documents. It gets in the way of people trying to use the main module documentation for reference.
• If there are modules on CPAN that do vaguely similar things (and these days when is this ever not the case :-) include a compare and contrast section. Show where your module is better and worse than the alternatives.
• Always have a "Why" for your "What". When you're explaining what a particular piece of API does, explain why you would want it to work in that way. For example when I originally wrote the description for startup and shutdown methods in Test::Class I didn't have the DBI example. I added it later because it makes it much more obvious why using that particular feature can be a good idea.
• Tree::Model doesn't tell me anything about what the module does apart from the fact is presumably has something to do with modelling trees?

(and before anybody points it out - yes I should follow more of my own advice with some of my modules :-)

---

---

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! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

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:
	&		&
	<		&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.