documentation: do we want perlblurb?

[Ricardo Signes]

A good long while ago, Uri proposed a document called "perlblurb." Without
getting into the document's specifics yet, it's a list of all the main
documents in ./pod, and each one is given a paragraph explaining the point.

The idea is that it provides a way for new users to quickly figure out where in
the docs to look, and what each "chapter" is about.

This is not the kind of document I'd be likely to use, but different people
like different kinds of documentation. I have attached Uri's draft, but let's
mostly stick to the idea of the document rather than the specifics.


--
rjbs

[Uri Guttman]

On 06/26/2015 10:10 PM, Ricardo Signes wrote:
> A good long while ago, Uri proposed a document called "perlblurb." Without
> getting into the document's specifics yet, it's a list of all the main
> documents in ./pod, and each one is given a paragraph explaining the point.

a minor expansion is that it also it meant to provide links to related
docs like a tute to a ref doc. a newbie wanting to learn more about
regexes might want to skip the perlre but realize perlretut is right for
them. e.g. each blurb on regex docs would say where they fit in the
newbie-guru spectrum. some blurbs may offer little perldoc tips like -v
for perlvar or -f for perlfunc.

and the language specific docs don't each get a paragraph. one para will
cover that whole list.

>
> The idea is that it provides a way for new users to quickly figure out where in
> the docs to look, and what each "chapter" is about.

given that the volume of docs will scare away some, perlblurb is meant
to be an easier navigation to the docs. perldoc perl just lists titles
and a short (cryptic?) one liner. perlblurb will deliver a focused
paragraph on what the doc is about, the target audience and related docs
to read as needed.

>
> This is not the kind of document I'd be likely to use, but different people
> like different kinds of documentation. I have attached Uri's draft, but let's
> mostly stick to the idea of the document rather than the specifics.
>

i wouldn't expect anyone on p5p to use perlblurb but i have run into
enough newbies who need some guidance through the docs. pointing them to
perlblurb will make their perl learning experience that much more effective.

thanx,

uri

[Uri Guttman]

On 06/27/2015 12:31 AM, Aristotle Pagaltzis wrote:
> * Uri Guttman <u...@stemsystems.com> [2015-06-27 06:00]:

>> given that the volume of docs will scare away some, perlblurb is meant
>> to be an easier navigation to the docs. perldoc perl just lists titles
>> and a short (cryptic?) one liner. perlblurb will deliver a focused
>> paragraph on what the doc is about, the target audience and related
>> docs to read as needed.

> Why a new document rather than an expansion of perltoc?
>
because a table of contents is not a blurb. i think the toc is useful
for a fast lookup of the proper name of a doc if you are experienced.
but expanding it to blurbs would defeat that quickness. perlblurb is
also meant to be browsed to get a scope of the perl docs. the toc is
just an index and should remain so IMO.

thanx,

uri

[Aristotle Pagaltzis]

* Uri Guttman <u...@stemsystems.com> [2015-06-27 06:00]:

> given that the volume of docs will scare away some, perlblurb is meant
> to be an easier navigation to the docs. perldoc perl just lists titles
> and a short (cryptic?) one liner. perlblurb will deliver a focused
> paragraph on what the doc is about, the target audience and related
> docs to read as needed.

Why a new document rather than an expansion of perltoc?

--
Aristotle Pagaltzis // <http://plasmasturm.org/>

[Uri Guttman]

also think of the toc as a quick guide/cheat sheet and perlblurb as a
tutorial. both are useful and target different audiences.

uri

[bulk 88]

----------------------------------------
> Date: Fri, 26 Jun 2015 22:10:19 -0400
> From: perl...@rjbs.manxome.org
> To: perl5-...@perl.org
> Subject: documentation: do we want perlblurb?

>
> A good long while ago, Uri proposed a document called "perlblurb." Without
> getting into the document's specifics yet, it's a list of all the main
> documents in ./pod, and each one is given a paragraph explaining the point.

-----------------------------------------------------
=head2 Tutorials

The documentation for Perl has a set of tutorials on a wide range of
topics. Pretty much any topic where you would want more explanation then
the reference documents will be covered in one of these.
-----------------------------------------------------

I would add this sentence somewhere in that section intro. "Compared with
the reference documents, tutorials are more verbose to be easier to read, but
slower to read and use as a reference."

Perl's pod docs are a disorganized mess on the relation of hashes,
packages, objects, references and globs. The tutorials never make it
clear, and instead encourage copypasta.

You can't make an object without knowing a reference, you can't stuff
anything but a scalar into a hash slice without a reference. globs are
strange "restricted hashes" of references. Each glob lives in a hash,
which also implements a package, and each package is made of globs.
Thanks to TMTOWTDI, the package keyword is not the only way to
make packages. Any vars created without "my" is a glob that lives
in a hash. A "module" (.pm) and a "package" have no technical
relationship. Any .pm can implement any package, and a .pm doesn't
need to implement the package its named after. %main:: is explained very
late perls POD. hash vs hash reference isn't clear, and many perl
programmers copy hashes instead of making references. Hash and arrays
are castable to each other through list context.

[Ed Avis]

That would leave three manual pages summarizing the others: perl, perltoc,
and perlblurb. Personally, I think just one would be enough: perl(1) could
list all the other pages with their table of contents and a short blurb if
wanted. Hitting PageDown or Space costs nothing so I don't think it matters
much to make the list a bit more verbose. And keyword search is certainly
easier within a single page rather than three.

--
Ed Avis <e...@waniasset.com>

[Aristotle Pagaltzis]

* Uri Guttman <u...@stemsystems.com> [2015-06-27 06:45]:

The TOC contains an oneliner and an outline on each doc. I don’t know
how you suppose me to think of that as a guide or cheat sheet. Anyway,
I’ve never once used it. Have you?

Whereas your blurbs are useful. Which is because the documentation is
so sprawling and disorganized. And the solution to too many documents
is… to add another?

Is it possible for something to simultaneously make a particular problem
better *and* worse? I’ve had no occasion to entertain that idea before…

Regards,

[Ricardo Signes]

* Aristotle Pagaltzis <paga...@gmx.de> [2015-06-27T06:43:33]

> The TOC contains an oneliner and an outline on each doc. I don’t know
> how you suppose me to think of that as a guide or cheat sheet. Anyway,
> I’ve never once used it. Have you?

I have used it, exclusively to figure out which perlfaq has the answer to some
almost-known question.

> Whereas your blurbs are useful. Which is because the documentation is
> so sprawling and disorganized. And the solution to too many documents
> is… to add another?

This is roughly my reaction as well.

Uri: you said it would impede the quick use of perltoc to add these blurbs to
it. But I'm not sure how. Can you elaborate?

--
rjbs

[Uri Guttman]

well, the perlblurb doc would be several times larger than the toc (1
line vs a para on each doc). i have used toc to find the proper name of
a doc sometimes and to show in one glance the range of docs to students
and such. it has its use as a toc and like blurb, few p5p people will
ever use it. a curious data point would to look at access logs on
perldoc.perl.org and see how often the toc is hit. i don't object to
making the toc be blurbs but my initial feeling was they are separate
docs. i have seen books like this, with a simple index of chapters and
then a short description of each chapter. they are more complimentary
than competitive IMO. again, think in terms of students and newbies and
needing quality guidance to the docs. your own uses have biases from
experience and hard to ignore.

i also wrote another doc that aims to help newbies use the perldocs. it
has a similar audience which is not p5p but those who get swamped with
the massive set of docs and the various tools to use them. that much
firehose directed at newbies is scary. one of perl's great strengths is
a quality and voluminous set of docs. perlblurb (and maybe perldoctut)
are meant to help navigate them. i didn't push perldoctut on rjbs this
time (i did the last time) but it could be looked at as a sister doc to
perlblurb. i have attached it (was called metadoc) for your enjoyment.

thanx,

uri

[Ricardo Signes]

* Uri Guttman <u...@stemsystems.com> [2015-06-27T12:00:45]

> well, the perlblurb doc would be several times larger than the toc (1 line
> vs a para on each doc). i have used toc to find the proper name of a doc
> sometimes and to show in one glance the range of docs to students and such.

Some documents have a useful short DESCRIPTION, like perlreftut. Others use
that section for a large introduction. Sometimes things work out strangely,
like the way perldsc shows up in the perltoc, with the =items from its
DESCRIPTION seeming to form a very terse description of their own.

I'm thinking that what might be best is to focus on how to make perltoc more
uniform and more useful. Part of that would be having an expected section in
the perlpods that is a one-paragraph summary, which shows up as the first-ish
thing in perltoc. The perlblurb texts would often be ideal for those
paragraphs. We can also look at making the structure of things a bit more
uniform, to make the toc itself more uniform.

I don't think these paragraphs will make toc less useful, since they'll
hopefully lead to replacing less useful stuff. The files might be longer, but
all files are equal in the eyes of search. (Well, not really, but nobody's
going to notice at these sizes. 😉 )


--
rjbs

[Uri Guttman]

i don't object to your ideas but i want to make sure the new content of the blurbs (whereever they land) is consistant and aimed correctly. i mentioned the goals before but it would be best if we had an 'official' list of points to make in each blurb. here is a rough pass at what i want to see:

1. what does this document cover?

This document covers Perl's regular expressions (pattern matching) in a quick guide. It is intended for those who know regexes but need to look up some detail quickly. It is for all Perl coders at any skill level. If you want to learn Regexes, see perlretut. For a printable cheat sheet of regex features, see perl???. for the complete reference document (long and detailed) see perlre.

that could be an intro para in perlrequick and also used in blurb or toc. if we play our cards right, we could semi-generate perlblurb from those intro paras in all the docs.

2. what is the target audience? (newbies, midlevel, gurus, internalists, etc.)

3. what are related docs (links)? similar topic, more/less skills needed, things to explore, etc.

and having just looked at perltoc again, it is very different than what i want to see in perlblurb. toc seems to be just extracted pod header lines and it isn't in normal english. topic titles aren't always clear as to who needs to read this or what. the para above is what i think is needed - a simple para clearly written for the audience to learn what a doc covers. topics are not the same as a blurb.

perldoc perl is a list of the docs with one line. perltoc is an extracted file of all the pod headers and such. perlblurb is in between. more than one liners, not a full list of topics. it is a place to browse and figure out what docs to read. i see perltoc as more for experience hackers to search for which doc covers a topic. newbies won't likely know what the search terms should be.

thanx,

uri

[Ricardo Signes]

* Uri Guttman <u...@stemsystems.com> [2015-06-27T20:25:10]

> perldoc perl is a list of the docs with one line. perltoc is an extracted
> file of all the pod headers and such. perlblurb is in between. more than one
> liners, not a full list of topics. it is a place to browse and figure out
> what docs to read. i see perltoc as more for experience hackers to search
> for which doc covers a topic. newbies won't likely know what the search
> terms should be.

You are saying "perltoc isn't meant to address this need."

I am saying, "it can address this need if we decided to make it do so."

--
rjbs

[Uri Guttman]

well, then i will counter with that would make toc way too large to
easily browse. a blurb for each doc followed by all the extracted topics
would be very hard to read quickly. i think toc should just be that as
it is more for searching than reading. perlblurb is meant to be read and
browsed and should be easy to do that. here, newbie, read perlblurb
first and then you will know what docs to read and maybe even in what
order (based on read next links and such). anyone can read perlblurb but
think about what you need to know to read toc. you need to understand
some perl/computer talk to know which topics are in your search. blurb
can be read by anyone with any skill level. they have different target
audiences.
blurb is in simple english. perldoc perl is terse and toc is very
technical. they need different content and writing styles.

and this is the point where i insult you gratuitously and make ad
hominem attacks.

your mother was a hamster.

uri