On Thu, Jul 1, 2010 at 17:18, Chas. Owens <chas.ow...@gmail.com> wrote: > I am excited to announce the formation of the Perl 5 Documentation > Team. Our goal is to have the best, most current, and easiest to use > and understand documentation of any programming language. Why settle > for small goals?
It's great that this is happening. And I hope that in general that changes that this team makes get the benefit of the doubt. It's somewhat important that everyone get a say and that every detail is covered, but even more important IMO that our documentaion is being *maintained*, which is hardly the case now. > Goals to be met for the Perl 5.14.0 release include: \o/ > * Extensive review and Modernization of all examples One thing I'd like to suggest. I think it'd improve our code examples a lot if we used a consistent style for them. By that I mostly mean not coding style (we've had that giant flamewar), but the sort of thing you find in "conventions used in this documentation" sections. E.g. consistently showing the return values of expressions like the Ruby and Python documentation do: http://ruby-doc.org/docs/ProgrammingRuby/html/tut_classes.html It's a lot easier to skim stuff like that than read I<The last call for this function returns xyz> or something similar in prose. > * Develop a plan to integrate with the [Pod2 translation project][4] It'd be great if we could get multilingular documentation of the ground. I think that for this to be fruitful we'd need a translation system so that translated documentation doesn't suffer bitrot. E.g. something similar to what translatewiki.org does to translate content, where things are split into paragraphs or sections and then assembled back again. Is there something like that already that can be used or improved? -- To unsubscribe, e-mail: beginners-unsubscr...@perl.org For additional commands, e-mail: beginners-h...@perl.org http://learn.perl.org/
