[Note: Posted to both perl6-language and perl6-documentation. Since perl6-documentation is no longer advertised, I assume follow ups should be posted to perl6-language only].
When Audrey gave a recent talk to Sydney.pm, she pointed out some deficiencies in the current Pugs/Perl 6 documentation and asked if I could help. Hence this email. In particular, she noted: * It is way too hard for newbies to come up to speed with p6 and Pugs because the documentation is scattered all over the shop and much of it (e.g. the Apocalypses and Exegeses) is dangerously out of date. * http://dev.perl.org/perl6/ needs updating. * http://www.pugscode.org/ needs updating. * It would be good to now start building the documentation that will eventually ship with Perl6 and Pugs. [Note that Pugs is just one implementation of Perl 6 the language (albeit the leading candidate for "Reference Implementation") thus there is a need for some Pugs-specific documentation.] Needless to add, she proposed that this documentation be built in the Pugs svn repository using the Pugs "anarchic" [TM] development model. After re-acquainting myself with Perl 6/Pugs and researching some Perl 6 documentation history, here are my thoughts: * I'm hopeful that the p6 spec has become stable enough that it now makes sense to press forward with p6 documentation. [It seems the lack of stability of the spec was one reason the "Perl 6 Documentation Project" stalled (list archives: http://www.nntp.perl.org/group/perl.perl6.documentation)]. * Having said that, I feel the Perl 6 spec itself properly belongs with @Larry and any (highly-skilled) volunteers they invite to help them. I doubt the Pugs development model will work well for this owing to the phenomenal skill level and precision required (just a personal opinion, I'm interested to hear what @Larry thinks). * I feel the Pugs model may work well for the non-formal-spec part (e.g. perlintro, pugsintro, tutorials, ...) of the documentation that will ship with Perl 6 and Pugs. Accordingly, that effort has already been started (mainly by Skud, so far) in the Pugs svn repository: http://svn.perl.org/perl6/pugs/trunk/docs/p6doc/. Call to Arms ============ Volunteers are sought for building the documentation that will ship with Perl 6 and Pugs. This documentation lives in the Pugs svn repository under docs/p6doc/. This documentation is being written in POD. If you want to contribute to this effort, hang around on the #perl6 IRC channel and ask someone for a committer bit. How should the documentation be organised? ========================================== Opinions are welcome on this. Certainly, there is much prior art on how to document a computer language. I feel we should essentially follow the p5 model, stealing good ideas from other languages (especially Ruby and Python) where appropriate. In particular, Ruby's PickAxe book seems a sound model for documenting the new p6 OO libraries. Though Audrey suggested modelling the documentation around p5's 'perldoc perl' command, I personally prefer the (similar) organisation at http://perldoc.perl.org/. References ========== * The Perl 6 Synopses, Apocalypses and Exegeses at: http://dev.perl.org/perl6/ (they are also stored in http://svn.perl.org repository). The Synopses are the most important of the three since they are the only ones being kept up to date. Some bits from current Pugs docs/ directory that might be useful: * docs/quickref/ (Juerd) * docs/articles/tpr.pod (gaal) draft (unpublished) TPR Pugs article * docs/other/porting_howto (iblech) How to port p5 modules to p6 * docs/notes/docs_evil_plan.txt (asavige) * examples/ directory (especially Ovid's cookbook) Some bits of Pugs docs/ directory needing more work: * 01Overview.html * 02Architecture.pod * 03Evaluator.pod * Pugs Apocrypha * Perl6::Bible (http://search.cpan.org/dist/Perl6-Bible/). * "Perl 6 Documentation Project" http://www.nntp.perl.org/group/perl.perl6.documentation * Rod Adams S29 at http://www.rodadams.net/Perl/S29.html * http://perldoc.perl.org/ * p5 'perldoc perl' command * The camel book * Python documentation http://www.python.org/ * PickAxe Reference section (for Perl Library Reference) * Parrot documentation (www.parrotcode.org) Send instant messages to your online friends http://au.messenger.yahoo.com
