"Joseph F. Ryan" wrote:
> Angel Faus wrote:
> >I think that the best way would be to create an schema of a language manual,
> >and fill the documents as we proceed reviewing the Apocalypses.
Agreed -- we should certainly figure out the overall structure first,
before doing much else. I think that's a pretty good start for an
outline, too.
Now given our intended goal of it being detailed enough for internals,
but written even for beginners, how do we "package" the materials?
(Should it be a concise language reference, a series of tutorials, a
formal or informal booklike document that explains everything in detail?
I know, I know, everyone's going to say "yes, all of them, and it
should dispense softdrinks from your CD-ROM drive upon request...")
We need a consensus, or at least a better argument ("booklike" currently
leads, but not in a statistically significant way.)
Thinking aloud:
We want the Perl community to grow. So how will newcomers to Perl6
learn about the language? That's a _really_ tough question, but I'm
willing to bet it's typically something like this:
When people first get an interest in Perl, they visit the online docs to
try and see what it's like. Then if they read through the initial stuff
and _still_ like Perl :-) they'll go out and buy a book or two on the
subject, which they will study. Once they get familiar with the
language, they'll go buy another few more specialized books, according
to their interest.
So it's the online docs that make-or-break that first decision --
whether to invest any time or money in learning Perl at all. If they
can't understand or don't like the basics of Perl from reading the
online docs, it will be harder to motivate them to pay for $50 books on
the subject, free software or not. It's just like any big decision: we
need to quickly build their confidence that they're dealing with
something they'll enjoy working with. If we can't, we lose them before
they even get to the bookstore, much less do any significant programming.
So what constitutes a "buy" decision for those potential Perl customers?
What would potential converts most want to see? A simple structure,
perhaps beginner-level things broken out from the advanced-level things?
Actual tutorials, or just really good explanations with examples? What
would get them to the next step -- the bookstore?
We can make some guesses based on our own experiences, and they might be
close, except that I think we are a profoundly self-selected group.
There may be some knowledgeable people we can ask this of, given our
connections (and the fact that as Perl grows, so do the markets of
companies that teach and document Perl.)
We might also want to put the question to the Perl public, in terms of
some quick online research (a questionnaire) -- Piers could announce it
in his summary, which would get us probably between 500-1000 responses.
(Still self-selected, but not nearly as bad.)
MikeL
--- P.S: ---
After users gain some experience, the role of the online/manpage
documentation shifts to one of "support". People will go to the docs if
any of these is true:
-- they have a very specific question
-- they have a very advanced question
-- they have a question their book(s) don't answer
-- they don't know enough about their question to know where to look for
it in the book.
The role of the docs then is to provide easy-to-find answers to a user's
questions. They will be "easy-to-find" if the site has been constructed
such that they've already learned where to find everything, when first
visiting the site on their initial "scouting missions."
MikeL
