in reply to writing docs and publishing on cpan

POD (Plain Old Documentation) is the proper format to write the docs in. CPAN has a list of suggested and required sections for submitted modules and scripts. I personally keep the POD at the end of the module source code, seperate from the code itself by an __END__ statement.

Publishing a module or script first requires a PAUSE id.
You can read more on submitting modules to CPAN and documenting them below: