This document outlines an evil plan for improving Pugs
documentation.

--- START AudreyT brain-dump ---------------------------------

This section is essentially disorganised notes taken while
AudreyT brain-dumped to asavige in Marrickville, Sydney
(while drinking caffeine-free Diet Coke) December 11 2005.
AudreyT: since I've liberally interpreted what you said,
please correct as you see fit.

Next day, Skud (author of Perl 5's perlintro) was leg-roped
into helping out at Audrey's Sydney.pm talk, then promptly
created a docs/p6doc directory with a view to gradually
growing a draft of the documentation that will eventually
ship with p6 (with a structure loosely modelled on p5
'perldoc perl'). For now, it seems best to use POD for this.
Perhaps a new 'p6doc' command will be created, similar to
the p5 'perldoc' command (perhaps p6doc implementation
will be based on Perl6::Bible 'p6bible' command).
It seems that p6-intro and pugs-intro are important and
should be done early to help those starting out with Pugs.
Also, it may be easiest to start with perlfaq, then
gradually build tutorials.

Perl6::Bible should be transformed into Perl6::Spec
(e.g. Perl::Spec::Operators, ...) to focus on the p6
specification, while removing dangerously obsolete material,
in particular the Apocalypses and Exegeses. Also, stub all
Synopses S01 .. S33; if they are empty, say so explicitly.
According to docs/AES, Liz is working on S17 (Concurrency),
Kane/Rafl on S22 (CPAN), Ingy/Mugwump on S26 (Perl Documentation),
Ingy on S27 (Perl Culture), Rod Adams on S29 (functions).
These have a status of "unofficial"; perhaps some of these
might be better called "draft" (though I guess that would
require agreement from @Larry). And auto-update Perl6::Spec
onto CPAN from svn regularly (alas, Perl6::Bible has fallen
out of date).

Note that Perl6::Spec should focus on *specification*, not
implementation. This is an important change from p5 (where
the implementation *was* the specification). Like Python
today, it is hoped there will be multiple p6 implementations
(of which Pugs is but one). To achieve that, the specification
*must* be nailed down precisely for the implementor.
Update: see Larry's response on this issue at:
http://www.nntp.perl.org/group/perl.perl6.language/24396

Perhaps the best way to organize the Perl Standard Library
is to model it on the reference section of the PickAxe (see
Summary p.423-426). Page 426 (change "Modules" to "Roles").
e.g. Enumerable. S29 should be folded into this (a la Ruby
Kernel module). S29 could be just a list of standard imports
with the details in the Perl Standard Library chapter.

As of December 2005, there are a number of problems with the
Pugs/Perl6 documentation:

* 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. In particular:
    -- the Architecture section is wrong
    -- the FAQ needs more work
    -- Lots of undefined jargon (e.g. strong v static typing)
    -- you can compile to native code
    -- the Talks section stops at 2004
    -- the Who's Who does not mention the Pugs team or Patrick Michaud
    -- the Status consists of only one vague line
    -- the Synopses are OK
    -- the Apocalypses and Exegeses and RFCs are out of date
    -- Planet Perl Six is not for the uniniated
  XXX: Does anyone know where the source code for this web
  site lives (svn.perl.org?) and the mechanism for updating
  it (Robert Spier?).

* http://www.pugscode.org needs updating.
    -- "I'd like to help..." needs expanding (and add link
       to pugs::hack)
    -- overview/download ok, rest needs work
    -- need a Pugs Architectural Overview

Some bits from current Pugs docs/ directory that might be useful:
   * docs/quickref/ (Juerd)
   * docs/articles/tpr.pod (gaal) TPR Pugs article
   * docs/other/porting_howto (iblech) How to port p5 modules to p6

Bits of Pugs docs/ directory needing more work:
   -- 01Overview.html
   -- 02Architecture.pod
   -- 03Evaluator.pod
   -- Pugs Apocrypha

--- END AudreyT brain-dump -----------------------------------

This section is extra ideas not in original AudreyT brain-dump.
Eventually, we trust this evil plan document will be transformed
into a more coherent form.

It is worth noting at this point that earlier efforts in this
area have not met with sparkling success:

* The "Perl 6 Documentation Project" (mailing list archives
  http://www.nntp.perl.org/group/perl.perl6.documentation)
  started in Nov 2002 and stalled about one year later.
  This project was led by Michael Lazzaro who complained
  it was "impossible to to coax p6l into a disciplined
  decision-making list" (which I guess is why it stalled).
  See also http://cog.cognitivity.com/perl6/.
  There are many names from that project that may be happy
  to help out here; those who registered interest then are:
  Michael Lazzaro, arcadi, Garret Goebel, Dave Storrs,
  Tanton Gibbs, Brent Dax, Markus Laire, Angel Faus,
  Andrew Wilson, Marco Escarcaga, Luke Palmer, Richard Nuttal,
  Dave Whipp, Jonathan Scott Duff, Allison Randal, Carlos Ramirez,
  Piers Cawley, Joseph Ryan, Erik Steven Harrison.

* Perl6::Bible (http://search.cpan.org/dist/Perl6-Bible/).
  Apart from a too-cute name and not being automatically
  updated, this CPAN module is cluttered with dangerously
  out-of-date material, notably the Apocalypses and Exegeses.
  The Apocalypses and Exegeses are now historical documents;
  only the Synopses are being kept up to date (in
  http://svn.perl.org/perl6/doc/trunk/design/syn/).

* Rod Adams S29 at http://www.rodadams.net/Perl/S29.html
  seems to have stalled ... well, the last update was made
  on 16 March 2005.

Language specifications (e.g. Guido for Python, Bjarne
for C++, ...) are traditionally written by the language
designer/s for the sound reason that they alone understand
the subject matter intimately enough to perform this exacting
task. Realistically, there appears little that non-Perl 6
design team folks can contribute in the area of documenting
the p6 Specification; that seems to be a job for @Larry.

However, the overall structure, tools (and some of the content)
of the documentation that will eventually ship with Perl 6
(i.e. docs/p6doc) does seem a realistic goal. Since this is
a big job, it seems sensible to offer committer bits to
participants in the old "Perl 6 Documentation Project".
Perhaps send a message to perl6-documentation@perl.org
asking for contributors (though I wasn't involved in
this project, it seems to have been focussed more on
the p6 specification rather than on the documentation
that will eventually ship with p6).

There is much (perhaps too much;-) prior art on how to document
a computer language (e.g. study how Ruby, Python, Java, Haskell,
... do it and steal the best ideas from each) ... or just convert
p5 perldoc to p6.

Some references that may prove useful:

* http://perldoc.perl.org/ (I prefer this to 'perldoc perl')
  Organised as follows:
    -- Overview
    -- Tutorials
    -- FAQs
    -- History/Changes
    -- License
    -- Reference
    --   Language
    --   Functions
    --   Operators
    --   Special variables
    --   Pragmas
    --   Core modules
    --   Utilities
    --   Internals
    --   Platform specific
    -- Links
    --   CPAN
    --   perl.com
    --   perl.org
    --   Perl Mongers
    --   Perl Monks
    --   Planet Perl
    --   Use Perl

* p5 'perldoc perl'
  Organised as follows:
    -- Overview
    -- Tutorials
    -- Reference Manual
    -- Internals and C Language Interface
    -- Miscellaneous
    -- Language-Specific
    -- Platform-Specific

* The camel book

* Python documentation http://www.python.org/
  Organised as follows:
    -- Tutorial
    -- Global Module Index
    -- Library Reference
    -- Language Reference
    -- Extending and Embedding
    -- Python C/API
    -- Documenting Python
    -- Installing Python Modules
    -- Distributing Python Modules

* Ruby http://www.ruby-lang.org/
    This looks a mess to me.

* PickAxe Reference section (for Perl Library Reference)

* dev.perl.org

* Perl6::Bible

* gaal's TPR article

* Pugs examples/ directory (especially Ovid's cookbook)

* Parrot documentation (www.parrotcode.org) -- Chip is taking
  parrot documentation very seriously (I applaud him for this)
  and I think a graduate student is currently working on it.

