[% setvar title Form a documentation working group to edit, clean, and producedocumentation %]

This file is part of the Perl 6 Archive

Note: these documents may be out of date. Do not use as reference!

To see what is currently happening visit http://www.perl6.org/


Form a documentation working group to edit, clean, and produce documentation


  Maintainer: Daniel Chetlin <daniel@chetlin.com>
  Date: 15 Sep 2000
  Mailing List: perl6-meta@perl.org
  Number: 240
  Version: 1
  Status: Developing


The Perl documentation suite is one of the best things going for Perl. It is thorough, well-written, informative, and enjoyable.

However, it was put together patchwork over a long period of time, and is extremely large and unwieldy. Some parts of the documentation have not been revised for years, even when they contain incorrect or outdated information.

This RFC proposes a way to manage documentation for Perl6, as well as give the Perl5 docs a much needed spring cleaning.


The RFC process has brought out a large number of people who want to discuss and debate aspects of Perl. It is the goal of this RFC to propose a method of harnessing this interest for the good not only of Perl6, but of Perl5 as well.

This proposed method is simple: a mailing list will be set up with an express purpose of editing, correcting, re-ordering, re-organizing, and expanding existing documentation.

This mailing list will not relate to proposals to change Perl; it will deal with Perl's current behavior only. When there is more information about the changes from Perl5 to Perl6, the documentation mailing list will begin incorporating those changes into the documentation. Until then, however, there is still plenty of work to be done, and no reason that this work cannot begin immediately.

The mailing list will concentrate on one .pod file at a time, devoting its entire collective energy on editing the .pod in question. The preferable way of submitting edits is via patches, but the mailing list chair will be responsible for incorporating edits that are submitted in other ways. After a reasonable amount of time, during which not only edits to the initial file, but also edits to the edits, are accepted, the mailing list chair will collect all changes into a master patch, and submit it to the perl5-porters mailing list for inclusion into the core. At that point, a new file will be selected for editing.

Here is a sketch of how a typical editing period might go:

While there is sure to be some discussion on this list (such as what files to work on and how to make certain changes), the main focus will be on doing, not talking.


Selection of a chair, creation of a list, and recruitment of interested parties is all that is required. The biggest win for this RFC is that it can be put into effect now and do some good not only for future Perl, but for current Perl as well.


The Perl documentation, as well as Tom Christiansen's excellent new perlman tools, which will be put through their paces by this proposal.