comment on

...slow clap with misty eyes...

FINALLY, someone said it. I don't know how many times I can read documentation and still not have a flipping clue how to start. And documentation without any example code at all? I'm sure the author is extremely brilliant, but if I don't know how to use the module, it doesn't matter. It ain't getting installed.

Next pet peeve would be modules requiring an extensive installation process without any documentation besides the copy/pasted ./configure; make; make install in the README. You know the ones. The ones that require jumping on your left foot backwards 7 steps under a harvest moon at midnight in a cemetery before they'll install correctly. I've been coding in perl for about 10 years and I DREAD a new module.

...Finally in desperation, pleading to the blessed holy monks for help. Only to receive the answer: "It's in the documentation."

...sigh...

In reply to Re: The problem of documenting complex modules. by ksublondie
in thread The problem of documenting complex modules. by BrowserUk

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.


There's more than one way to do things
	PerlMonks