Re: Roll Call

Dave Storrs wrote:

>Well, I'm here, FWIW.
>
>Here's my 2 copper Lincolns regarding scope and topics:
>
>I see a place for each of the following kinds of documentation:
>	- "How do I get started helping on Parrot"?
>	- "What do the guts of Parrot look like and why?"
>	- "I am a programmer with no Perl experience.  Tell me why I should switch to Perl6."
>	- "I am a Perl5 programmer.  Tell me why I should switch to Perl6."
>	- Online docs, a la the existing perlvar, perlfunc, etc
>	- Tutorials, a la the existing perltoot
>
>wrt the first two...some documents of this sort already exist, but we could see what we can do to help/consolidate/clean them.
>
>wrt the last two...we may or may not want to use the existing formats.  There was a discussion just recently of "cookbook" versus "online book" style.  I personally favor "book", because cookbooks are less when you have a problem that isn't explicitly addressed, but that's just MO.
>  
>
Useful List. I presonally use a combination of documentation for 
programming, and
find the Perl documentation more difficult to use than many. Generally, 
I'd like
an online 'database' of documentation.

www.mysql has an excellent online reference and I can always find what I 
need there
for MySql. Clearly we don't need to copy exactly, but the fact of a key 
documentation
resource being online, able to be added to and quick and easy to use is 
great.

perlfunc, et al. are OK for a "what parameters do I use for this 
function", but for
example code, updates, etc, it has to be online.

I expect to be mostly a lurker on this list, but am prepared to put some 
effort into any online documentation effort. Presumably this would be 
written in Perl6 ? Actually I mostly use PHP
currently (again, this has an excellent online reference manual, with 
places for people to add
sample code snippets), since I find it lighter weight and more 
integrated for dynamic webpage
generation when linked to a database.

(Part of the reason that PHP and MySQL have good references is that they 
are primarily maintained by one small development team. If we can 
harness the strengths of those approaches, while maintaining the 
Perlness of the Perl documentation, it'll be a great resource.)

One further comment on the differences. Bother MYSQL and PHP are much 
more simple languages, and the bulk of their references are functional, 
breaking down into a neat hierarchy. Perl6 needs documentation that 
slices a number of ways, since the syntax and structures are much richer 
and need much more explanation, specially to newbies. This is again 
where an online, web-based resource will work well.

Hope that's not too much of a ramble.

R.

-- 
Richard Nuttall
Invisible Networks
Tel: 01954 200002
DDI: 01954 206361
Mob: 07798 528923
Fax: 01954 206360
Web: www.invisible.uk.net