I'm probably as much a "CPAN programmer" as Perl programmer, since there's so much stuff out there that's already done that helps me solve my problems.
The single most valuable thing to me in module documentation is a few little snippets of working code that I can paste in and run as a starting point. It removes ambiguity over what really needs to be done in setup and what needs to be passed where. Ideally for a complex module there will be a few examples that address likely use cases of people coming to the module for the first time. They don't have to be complicated, but if they address in a few lines what I might have spent a bunch of time trying to sort through without the module, then they a) show me that the module can address my problem, and b) give me an entry point where I can start building my bigger solution without having to spend a bunch of time just trying to get started.
-
Are you posting in the right place? Check out Where do I post X? to know for sure.
-
Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
<code> <a> <b> <big>
<blockquote> <br /> <dd>
<dl> <dt> <em> <font>
<h1> <h2> <h3> <h4>
<h5> <h6> <hr /> <i>
<li> <nbsp> <ol> <p>
<small> <strike> <strong>
<sub> <sup> <table>
<td> <th> <tr> <tt>
<u> <ul>
-
Snippets of code should be wrapped in
<code> tags not
<pre> tags. In fact, <pre>
tags should generally be avoided. If they must
be used, extreme care should be
taken to ensure that their contents do not
have long lines (<70 chars), in order to prevent
horizontal scrolling (and possible janitor
intervention).
-
Want more info? How to link
or How to display code and escape characters
are good places to start.
|
