Not sure why you have to treat code samples differently for translation purposes - surely the translation of
/*
* print 'hello world'
*/
echo 'Hello world';
is something like
/*
* print 'bonjour le monde'
*/
echo 'bonjour le monde';
(You'll note I don't speak French ...)
and the code samples can be treated exactly the same as any other block of text.
I don't think reducing the number of comments in the text is a good idea at all - you just make the manual less useful for those who can speak English, without adding any benefit for those who can't.
Just my opinion - there may be good reasons for the choice which I don't understand!
If there is going to be a manual reorganisation, can I add a couple of suggestions:
1) put the up & home links (or better yet, breadcrumb trail) at the top of each page, not just the bottom
2) maybe add a 'comments' section or similar to the sections, similar to the PHP manual. Although there's a huge amount of dross in the PHP manual comments, I found them very useful when I was starting to code. Not sure if ZF lends itself to such pithy comments & code samples, however.
3) improve the menu. It would be handy to see the table of contents for a chapter while reading that chapter, rather than having to (scroll to the bottom and) click the 'up' link. Maybe in that dead space on the left?
Anyway, good work on the reorganisation!
On Sat, Mar 21, 2009 at 8:29 PM, mikaelkael <perraud.mickael@orange.fr> wrote:
> Hi all,
>
> The proposal to reorganize the documentation is now ready for review:
>
http://framework.zend.com/wiki/pages/viewpage.action?pageId=8947295>
> The main goals are:
> -simplification of management
> - simplification of translation
> - simplification of rendering
>
> All comments are welcome.
>
> In the same time, I want to give you a link to test a base for a new
> translator tool. It isn't an editor ;).
> It is a tool to replace the
http://framework.zend.com/manual/status.
> It is NOT THE tool, it's a base of work. See
>
http://mikaelkael.dyndns.org/checkzf>
> Mickael
>
>
