Re: version-0.77 and You

On Wed, Jul 15, 2009 at 10:13 AM, David Golden <[email protected]> wrote:

>
> Easiest is just to park it on the QA wiki, I think.  Maybe hang it off the
> toolchain roadmap page?
>

A copy of my edits is attached and I've put a copy on the QA Wiki:

http://perl-qa.hexten.net/wiki/index.php/Version_POD

My goal with this structural revision was assuming the people don't read
docs (much) so trying to have a very logical top-down structure from the
table of contents (as created by search.cpan.org).  I tested the pod on
search here: http://search.cpan.org/pod2html

I expanded on the synopses a bit and I also tried to make sure that good
practices were reflected consistently and I removed some text about bad
practices for brevity. For example, I removed the new() method description
since we want to discourage its use anyway.

Most of the text is still John's -- I mostly re-arranged and streamlined.
In a couple areas (parsing & comparison) I wrote new text.  In some other
areas (eg. alphas) I copied text from the Internals POD and then edited to
fit.

John -- I hope you see this as a step forward.  I think it will be much more
prescriptive in describing how people should use version.pm -- and then the
more detailed Internals POD is there for those who really need to see it.

-- David