On Mon, Jun 13, 2011 at 03:42:49AM -0400, Uri Guttman wrote: > i said i was working on a perl metadoc and here is the first draft... > > Perl is blessed with an extensive set of accurate and informative > documentation. But that means it is harder for newcomers to Perl to > navigate through the forest of pages. This document aims to be a guide > to the Perl documentation. Its goals are to cover where to find the > documents, what are the kinds of documents, how to best read them, what > tools are available, what other resources there are and more. That is > why this document is called perlmetadoc as it is about the other > documents.
Rather prolix! Sesquipedalian, even! How about this ... " Perl has lots of documentation, but it can be hard to know what you need to read and when. This is a guide to help you find your way. It will also tell you about tools for reading the documentation and other places to get help. " Documentation, especially that for beginners, and extra-especially that intended to be read by people for whom English is a second or even a third language (and perldoc should definitely be so intended!), should be clear, simple and concise. Avoid flowery phrasing (blessed with), minimise redundancy (accurate and informative? well of *course* it's accurate and informative, we wouldn't publish a load of lies would we?), minimise use of long words (navigate, newcomers), minimise metaphor (forest of pages), expunge everything that's unnecessary (why the document is called what it is). Of course, keeping this up is bloody hard work so I'm going to stop there :-) -- David Cantrell | Nth greatest programmer in the world There is no one true indentation style, But if there were K&R would be Its Prophets. Peace be upon Their Holy Beards. _______________________________________________ Boston-pm mailing list [email protected] http://mail.pm.org/mailman/listinfo/boston-pm
