Thursday, July 1, 2010

Announcing the Perl 5 Documentation Team

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, 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 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 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

@Adam This is a good point that I had not even considered. I was thinking of only improving the core documentation, but you are right, there is more to documentation than the core docs. I will have to think about what to cover; I guess this means researching what Ruby has done.