I am excited to announce the formation of the Perl 5 Documentation
Team. Our goal is to have the best, most current, and easiest to use
and understand documentation of any programming language. Why settle
for small goals?
Since the success of this team will depend on having both expert and
novice points of view, membership is open to all, regardless of
experience level with Perl. This is an excellent opportunity for
people who would like to make a contribution back to the Perl
community to do so in a way that doesn't require expert programming
abilities.
If you are interested in being part of the team, please subscribe to
[the Perl Documentation mailing list][1], as future discussion will
occur there (look for the thread named "I want to sign up"). If you
know of other people who may be interested in being part of this
effort, please pass this message on to them.
Areas where the team will be active include:
* Reviewing and updating documentation to ensure that it is
friendly to new users
* Updating examples in documentation to a style compatible with
Modern Perl practices
* Updating the documentation so that all examples longer than one
line contain a `use` statement indicating the minimum version of
Perl 5 required to run the example
* Monitoring [p5p][2] for incoming documentation patches, ensuring
they contain a patch against the current delta, and forwarding
them to committers as needed
* Monitoring p5p for patches that will require modification of
documentation, and ensuring that the documentation is modified
appropriately
* Verifying that perlglossary contains current accurate
definitions for all jargon terms
Goals to be met for the Perl 5.14.0 release include:
* Recruit novice and experienced Perl programmers to the team, and
create a Perl module (a la Perl::Staff) and a Perl 5 wiki entry
listing the team members
* Finalize [perlopquick][3] as a replacement for perlop and
modify the new perlop so that perlop and a shorter perlopref can
be generated from a single source document
* Extend perldoc to use the new perlop to provide documentation on
operators (tenative proposal: perldoc -O "^=")
* Create a perlfuncref, a series of short summaries of information
in perlfunc, analogous to perlopref (Again, both of these will
be generated from a single source document for ease of
maintenance)
* Define a policy for documenting documentation changes in
the Perl deltas (e.g. perl5133delta.pod)
* Define a set of documentation style guidelines, covering
structure, style, and content
* Formally define the Perl 5 Documentation Team functions
* Set deadlines for the defining of longer term goals
* Create a logo for the Perl 5 Documentation Team
* Find a better name or nickname for the Perl 5 Documentation Team
Potential longer term (post-5.14.0) goals:
* Clean up perlre
* Extensive review and Modernization of all examples
* Develop a plan to integrate with the [Pod2 translation project][4]
[1]: http://lists.perl.org/list/perl-documentation.html
[2]: http://lists.perl.org/list/perl5-porters.html
[3]: http://github.com/cowens/perlopquick
[4]: http://pod2.perl.org/
--
Chas. Owens
wonkden.net
The most important skill a programmer can have is the ability to read.
--
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
http://learn.perl.org/
