On Thu, Jul 1, 2010 at 17:29, Ævar Arnfjörð Bjarmason <ava...@gmail.com> wrote: snip >> * 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 snip
One of the things I have been doing is using a comment after a line stating what the result of line is. snip >> * 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? snip These are the sort of things that cause this to be a long term goal. One of my first thoughts was that we should just machine translate the whole of the documentation into a bunch of languages and then let people apply patches to correct the hilariously bad machine translations. -- Chas. Owens wonkden.net The most important skill a programmer can have is the ability to read.
