develooper Front page | perl.perl5.porters | Postings from March 2011

Rethinking some perldocs (Re: Revising Perl's OO docs - a new OO tutorial)

Thread Previous | Thread Next
From:
brian d foy
Date:
March 3, 2011 21:17
Subject:
Rethinking some perldocs (Re: Revising Perl's OO docs - a new OO tutorial)
Message ID:
030320112317473286%brian.d.foy@gmail.com
In article <31400.1299175742@chthon>, Tom Christiansen
<tchrist@perl.com> wrote:

> Please don't include anything in the standard distribution
> that tells people they can't use the standard distribution.
> 
> If you want to include something in the standard distribution
> whose entire focus is outside the standard distribution, then 
> you should bring the thing that is outside, inside.

The summary: can we reduce the size of the list in perl.pod and replace
major sections of the docs with new material not based on what's
already there?

Some of Dave's work on his new OO tutorial may have come out of a Perl
heretic talk I gave in Minneapolis around Halloween: 

http://www.slideshare.net/brian_d_foy/perldocs

The non-core-reference documented has accreted in an unplanned way
based on whatever people wanted to contribute. It's nice that the
information is there, but not so nice for the person who has to find it
or decide what to read. The terse naming scheme and lack of hierarchy
confuses ordinary people.

For instance, where do you find the rules and documentation about
creating variables? It's not in perlvar. While it might make sense to
us that it's in perlsyn, to the newbie who sees a doc page that says
"var", that's the first place they'd naturally want to look.

Similarly, we have swirling around the core reference various quick
starts, tutorials,  faqs, and so on. 

So, when it comes to OO, what should the new person read? Although Dave
doesn't go so far as saying that he wants to replace the various
non-reference pods, I think that's what should happen. Can we collapse
perltoot, perlboot, perlobj, perlmod, and perlmodlib into fewer
documents? Do we have to keep a particular document merely because it
has always been there evne though no one is updating it?

The problem, of course, is that you have to treat several topics almost
simultaneously, including the Perl object system, the package and
namespace system, references, and distributions, as well as popular
add-ons from CPAN. Dave also correctly recognizes that most people
suffer because they don't grasp OO from the start, so they already have
a disadvantage.

So, there are various fantasies I have about what the pod/ directory
could be and how that might help people.

First, I'd want to organize it:

     pod/
          reference
          tutorials
          quickstarts
          faq
          os-specific
          changes
          unicode
          &c.

Those are the easy ones, but then we can get a little sloppy. Old docs
don't have to go away, they just have to find a new home that's out of
the way. We can also be a bit looser with contributions, like Dave's, 

     pod/
          contributed  (third-party, whatever)
          legacy (old, unsupported, whatever)

I also hear that we are abandoning the 8.3 filesnames, which some of
the pod files already ignore, so can we make better names and get rid
of the useless four characters at the front (except maybe for
installing man pages):

     pod/
          references/
               variables.pod
               syntax.pod
               operators.pod

If we really wanted to get crazy:

     pod/
          references/
               functions/
                    open.pod

With some changes to Pod::Perldoc, we can support the hierarchy with
the old names as a deprecation cycle:

     $ perldoc5.16 perlsyn
     Warning: perlsyn is now syntax, use `perldoc syntax`

People don't have to know the hierarchy to find the docs with perldoc
because we'll do that for them. However, when they go to
perldoc.perl.org or a similar site where they aren't using perldoc,
they have a leg up.

Next, in various docs, as appropriate and especially for tutorials, I'd
put in hints on what the reader should already have looked at, and add
more cross references. The goal is to reduce the repeated information
(such as the here docs stuff I just patched in perlfaq and perldiag).
From there, I'd make a map that shows the relationship of the docs (as
we say in the Army "A graphical depiction of the earth as seen from
above"). It would be grand if I could also figure out how to direct the
person the the right starting point in the map. Although I could do
that in Inform, maybe, then we'd have to add a z-code runner to core.
:)

Some of this begs for a bit more structure. We don't do much with X<>,
and it would be nice to have structured info that comes out of X<> or
L<> or maybe something new ( R<reference>? ) that allows us to make
that map as part of building perl.

That's enough for tonight.

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About