How to contribute to ZF2 documentation project

classic Classic list List threaded Threaded
16 messages Options
Reply | Threaded
Open this post in threaded view
|

How to contribute to ZF2 documentation project

Enrico Zimuel-2
Hi all,

i just wrote this post on devzone.zend.com on how to contribute to the
ZF2 documentation project:

http://devzone.zend.com/2463/zf2-documentation-we-want-you/

In the post I put evidence on the contribution process and how to use
the "Edit this document" button in the zf2.readthedocs.org site.

Help us to spread this post, thanks!

--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com
Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

harikt
This post has NOT been accepted by the mailing list yet.
Good post . But images are missing.

Hari K T
M: +91-9388758821 | W: http://harikt.com/blog



On Thu, Aug 2, 2012 at 4:41 PM, Enrico Zimuel-2 [via Zend Framework Community] <[hidden email]> wrote:
Hi all,

i just wrote this post on devzone.zend.com on how to contribute to the
ZF2 documentation project:

http://devzone.zend.com/2463/zf2-documentation-we-want-you/

In the post I put evidence on the contribution process and how to use
the "Edit this document" button in the zf2.readthedocs.org site.

Help us to spread this post, thanks!

--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com



If you reply to this email, your message will be added to the discussion below:
http://zend-framework-community.634137.n4.nabble.com/How-to-contribute-to-ZF2-documentation-project-tp4656046.html
To start a new topic under ZF Contributor, email [hidden email]
To unsubscribe from ZF Contributor, click here.
NAML

Hari K T http://harikt.com
Reply | Threaded
Open this post in threaded view
|

RE: How to contribute to ZF2 documentation project

BullfrogBlues
In reply to this post by Enrico Zimuel-2





> Date: Thu, 2 Aug 2012 13:08:44 +0200

> From: [hidden email]
> To: [hidden email]
> Subject: [zf-contributors] How to contribute to ZF2 documentation project
>
> Hi all,
>
> i just wrote this post on devzone.zend.com on how to contribute to the
> ZF2 documentation project:
>
> http://devzone.zend.com/2463/zf2-documentation-we-want-you/
>
> In the post I put evidence on the contribution process and how to use
> the "Edit this document" button in the zf2.readthedocs.org site.
>
> Help us to spread this post, thanks!
>
> --
> Enrico Zimuel
> Senior PHP Engineer | [hidden email]
> Zend Framework Team | http://framework.zend.com
> Zend Technologies Ltd.
> http://www.zend.com


Hi,

What is preferred way to submit pull requests for trivial changes such as grammer and typos. Indivdual pull requests as you come across them or one pull request per page?

--
Gerry

Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Mickael Perraud
In reply to this post by Enrico Zimuel-2
Hi all,

Is it allowed to begin translation? It seems not for the moment => https://github.com/zendframework/zf2-documentation/pull/119

I really don't understand comment like: "I know there is a bug, I know that you correct it, I simply don't want to apply your PR".

Can you clarify this point, I don't want a battle each I will have a PR.

Thanks in advance
.
--
Mickaël Perraud

Website | http://mikaelkael.fr
Twitter | http://twitter.com/mikaelkael
PGP key | http://mikaelkael.fr/mikaelkael.asc



2012/8/2 Enrico Zimuel <[hidden email]>
Hi all,

i just wrote this post on devzone.zend.com on how to contribute to the
ZF2 documentation project:

http://devzone.zend.com/2463/zf2-documentation-we-want-you/

In the post I put evidence on the contribution process and how to use
the "Edit this document" button in the zf2.readthedocs.org site.

Help us to spread this post, thanks!

--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com

Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Mickael Perraud
Hi all,

After some exchanges (see PR comments), it seems that the current structure is only valid for English documentation. The migration to reST lost some good practices that we adopt for translation with ZF1 (see http://framework.zend.com/code/revision.php?repname=Zend+Framework&path=%2Ftrunk%2Fdocumentation%2Fmanual&rev=19859&peg=25010 for example).

Do you want that I reapplied this practices with new ZF2 structure?
--
Mickaël Perraud

Website | http://mikaelkael.fr
Twitter | http://twitter.com/mikaelkael
PGP key | http://mikaelkael.fr/mikaelkael.asc



2012/8/6 Mickael Perraud <[hidden email]>
Hi all,

Is it allowed to begin translation? It seems not for the moment => https://github.com/zendframework/zf2-documentation/pull/119

I really don't understand comment like: "I know there is a bug, I know that you correct it, I simply don't want to apply your PR".

Can you clarify this point, I don't want a battle each I will have a PR.

Thanks in advance
.
--
Mickaël Perraud

Website | http://mikaelkael.fr
Twitter | http://twitter.com/mikaelkael
PGP key | http://mikaelkael.fr/mikaelkael.asc



2012/8/2 Enrico Zimuel <[hidden email]>
Hi all,

i just wrote this post on devzone.zend.com on how to contribute to the
ZF2 documentation project:

http://devzone.zend.com/2463/zf2-documentation-we-want-you/

In the post I put evidence on the contribution process and how to use
the "Edit this document" button in the zf2.readthedocs.org site.

Help us to spread this post, thanks!

--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com


Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

weierophinney
Administrator
In reply to this post by BullfrogBlues
-- Gerry - <[hidden email]> wrote
(on Saturday, 04 August 2012, 12:18 AM +0100):
> What is preferred way to submit pull requests for trivial changes such as
> grammer and typos. Indivdual pull requests as you come across them or one pull
> request per page?

It'd probably be easier for reviewers to have one PR per page. However,
if you don't want to/have time to review the entire page in one go,
multiple PRs can be used.

--
Matthew Weier O'Phinney
Project Lead            | [hidden email]
Zend Framework          | http://framework.zend.com/
PGP key: http://framework.zend.com/zf-matthew-pgp-key.asc
Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Enrico Zimuel-2
In reply to this post by Mickael Perraud
Hi Mickael,

I see the problem for the translation of zf2-documentation.
Right now we don't have all the files translated and if you try to
compile the docs you will get errors (missing files).

I see two ways to manage this issue:

1) change the index.rst file (Table Of Contents) for each languages to
include only the translated files;

2) modify the Makefile to be able to copy the missing files from
/docs/languages/en and copy to the local languages throwing a message to
the user that say something like "The xxx file is missing from the
translation, I used the english file as temporary file"

I just discovered that you are already working on the second solution :)
https://github.com/mikaelkael/zf2-documentation/commit/9a21dca53966b03e8e32f666c601b8a21298ac06

That's great!
I think we can work on the second solution.
Folks any other ideas on that?

Regards,
Enrico Zimuel

On 08/06/2012 09:46 AM, Mickael Perraud wrote:

> Hi all,
>
> Is it allowed to begin translation? It seems not for the moment =>
> https://github.com/zendframework/zf2-documentation/pull/119
>
> I really don't understand comment like: "I know there is a bug, I know that
> you correct it, I simply don't want to apply your PR".
>
> Can you clarify this point, I don't want a battle each I will have a PR.
>
> Thanks in advance.
> --
> Mickaël Perraud
> Website | http://mikaelkael.fr
> Twitter | http://twitter.com/mikaelkael
> PGP key | http://mikaelkael.fr/mikaelkael.asc
>
>
>
> 2012/8/2 Enrico Zimuel <[hidden email]>
>
>> Hi all,
>>
>> i just wrote this post on devzone.zend.com on how to contribute to the
>> ZF2 documentation project:
>>
>> http://devzone.zend.com/2463/zf2-documentation-we-want-you/
>>
>> In the post I put evidence on the contribution process and how to use
>> the "Edit this document" button in the zf2.readthedocs.org site.
>>
>> Help us to spread this post, thanks!
>>
>> --
>> Enrico Zimuel
>> Senior PHP Engineer     | [hidden email]
>> Zend Framework Team     | http://framework.zend.com
>> Zend Technologies Ltd.
>> http://www.zend.com
>>
>


--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com
Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Mickael Perraud
Hi Enrico,

I prefer the second solution because when an user read a translated documentation, he can understand that some parts are not translated but he want an complete and *up-to-date* documentation.

I want now to point out the difficulties of the translators with ZF1 documentation. To be clear, I am absolutely not against the migration from DocBook to reST but I will use the example of our work with DocBook to propose what we can do with reST.

Even if the translation can be a difficult work, maintain a translation is certainly the most difficult part of the work. Then we adopted some rules to simplify the work of maintainers:
 1) Remove the (manual.xml | index.rst) in each language => this limits the forgetting of a line when adding a file in the main documentation
 2) Put any translation outside the (manual.xml | index.rst) file => if we remove index.rst, we need to provide an alternative to translate title for example. We resolved it with XML entities with Docbook. The question is opened for reST
 3) Allow translators to easily detect modifications in English files => with ZF1, I created a translator tool (http://mikaelkael.dyndns.org/checker/) that can detect them with the help of a specific tag (exactly the same as PHP documentation). With Docbook and SVN it's a comment tag with the English revision number on which the translated file is based: "<!-- EN-Revision: 25000 -->". With reST and Git, it can be something like: ".. EN-Revision: 9a21dca" at the top/bottom of the file. Of course, with this, I will update the translator tool.

Next point is about http://readthedocs.org/. Currently they don't provide support for i18n (https://github.com/rtfd/readthedocs.org/issues/139) and even if they apply this PR (https://github.com/rtfd/readthedocs.org/pull/193), they will support the structure proposed by Sphinx (http://sphinx.pocoo.org/intl.html). Then a translation of ZF2 documentation can't be rendered by RTFD with the current structure. Of course we always have http://packages.zendframework.com/docs/latest/manual/en/ but it can be a good thing if we can render translated documentations.

Regards,
--
Mickaë
l Perraud
Website | http://mikaelkael.fr
Twitter | http://twitter.com/mikaelkael
PGP key | http://mikaelkael.fr/mikaelkael.asc



2012/8/6 Enrico Zimuel <[hidden email]>
Hi Mickael,

I see the problem for the translation of zf2-documentation.
Right now we don't have all the files translated and if you try to
compile the docs you will get errors (missing files).

I see two ways to manage this issue:

1) change the index.rst file (Table Of Contents) for each languages to
include only the translated files;

2) modify the Makefile to be able to copy the missing files from
/docs/languages/en and copy to the local languages throwing a message to
the user that say something like "The xxx file is missing from the
translation, I used the english file as temporary file"

I just discovered that you are already working on the second solution :)
https://github.com/mikaelkael/zf2-documentation/commit/9a21dca53966b03e8e32f666c601b8a21298ac06

That's great!
I think we can work on the second solution.
Folks any other ideas on that?

Regards,
Enrico Zimuel

On 08/06/2012 09:46 AM, Mickael Perraud wrote:
> Hi all,
>
> Is it allowed to begin translation? It seems not for the moment =>
> https://github.com/zendframework/zf2-documentation/pull/119
>
> I really don't understand comment like: "I know there is a bug, I know that
> you correct it, I simply don't want to apply your PR".
>
> Can you clarify this point, I don't want a battle each I will have a PR.
>
> Thanks in advance.
> --
> Mickaël Perraud
> Website | http://mikaelkael.fr
> Twitter | http://twitter.com/mikaelkael
> PGP key | http://mikaelkael.fr/mikaelkael.asc
>
>
>
> 2012/8/2 Enrico Zimuel <[hidden email]>
>
>> Hi all,
>>
>> i just wrote this post on devzone.zend.com on how to contribute to the
>> ZF2 documentation project:
>>
>> http://devzone.zend.com/2463/zf2-documentation-we-want-you/
>>
>> In the post I put evidence on the contribution process and how to use
>> the "Edit this document" button in the zf2.readthedocs.org site.
>>
>> Help us to spread this post, thanks!
>>
>> --
>> Enrico Zimuel
>> Senior PHP Engineer     | [hidden email]
>> Zend Framework Team     | http://framework.zend.com
>> Zend Technologies Ltd.
>> http://www.zend.com
>>
>


--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com

Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Maks3w
In reply to this post by Enrico Zimuel-2

I think that we can adapt the index to include english equivalent files while the french version is not translated yet.


De: Enrico Zimuel <[hidden email]>
Para: [hidden email]
Enviado: Lunes 6 de agosto de 2012 18:55
Asunto: Re: [zf-contributors] How to contribute to ZF2 documentation project

Hi Mickael,

I see the problem for the translation of zf2-documentation.
Right now we don't have all the files translated and if you try to
compile the docs you will get errors (missing files).

I see two ways to manage this issue:

1) change the index.rst file (Table Of Contents) for each languages to
include only the translated files;

2) modify the Makefile to be able to copy the missing files from
/docs/languages/en and copy to the local languages throwing a message to
the user that say something like "The xxx file is missing from the
translation, I used the english file as temporary file"

I just discovered that you are already working on the second solution :)
https://github.com/mikaelkael/zf2-documentation/commit/9a21dca53966b03e8e32f666c601b8a21298ac06

That's great!
I think we can work on the second solution.
Folks any other ideas on that?

Regards,
Enrico Zimuel

On 08/06/2012 09:46 AM, Mickael Perraud wrote:

> Hi all,
>
> Is it allowed to begin translation? It seems not for the moment =>
> https://github.com/zendframework/zf2-documentation/pull/119
>
> I really don't understand comment like: "I know there is a bug, I know that
> you correct it, I simply don't want to apply your PR".
>
> Can you clarify this point, I don't want a battle each I will have a PR.
>
> Thanks in advance.
> --
> Mickaël Perraud
> Website | http://mikaelkael.fr
> Twitter | http://twitter.com/mikaelkael
> PGP key | http://mikaelkael.fr/mikaelkael.asc
>
>
>
> 2012/8/2 Enrico Zimuel <[hidden email]>
>
>> Hi all,
>>
>> i just wrote this post on devzone.zend.com on how to contribute to the
>> ZF2 documentation project:
>>
>> http://devzone.zend.com/2463/zf2-documentation-we-want-you/
>>
>> In the post I put evidence on the contribution process and how to use
>> the "Edit this document" button in the zf2.readthedocs.org site.
>>
>> Help us to spread this post, thanks!
>>
>> --
>> Enrico Zimuel
>> Senior PHP Engineer    | [hidden email]
>> Zend Framework Team    | http://framework.zend.com
>> Zend Technologies Ltd.
>> http://www.zend.com
>>
>


--
Enrico Zimuel
Senior PHP Engineer    | [hidden email]
Zend Framework Team    | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com


Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Mickael Perraud
In this case, each time that I want to translate a file so I need to think to change the index.rst
--
Mickaël Perraud
Website | http://mikaelkael.fr
Twitter | http://twitter.com/mikaelkael
PGP key | http://mikaelkael.fr/mikaelkael.asc



2012/8/6 Maks3w <[hidden email]>

I think that we can adapt the index to include english equivalent files while the french version is not translated yet.


De: Enrico Zimuel <[hidden email]>
Para: [hidden email]
Enviado: Lunes 6 de agosto de 2012 18:55
Asunto: Re: [zf-contributors] How to contribute to ZF2 documentation project

Hi Mickael,

I see the problem for the translation of zf2-documentation.
Right now we don't have all the files translated and if you try to
compile the docs you will get errors (missing files).

I see two ways to manage this issue:

1) change the index.rst file (Table Of Contents) for each languages to
include only the translated files;

2) modify the Makefile to be able to copy the missing files from
/docs/languages/en and copy to the local languages throwing a message to
the user that say something like "The xxx file is missing from the
translation, I used the english file as temporary file"

I just discovered that you are already working on the second solution :)
https://github.com/mikaelkael/zf2-documentation/commit/9a21dca53966b03e8e32f666c601b8a21298ac06

That's great!
I think we can work on the second solution.
Folks any other ideas on that?

Regards,
Enrico Zimuel

On 08/06/2012 09:46 AM, Mickael Perraud wrote:
> Hi all,
>
> Is it allowed to begin translation? It seems not for the moment =>
> https://github.com/zendframework/zf2-documentation/pull/119
>
> I really don't understand comment like: "I know there is a bug, I know that
> you correct it, I simply don't want to apply your PR".
>
> Can you clarify this point, I don't want a battle each I will have a PR.
>
> Thanks in advance.
> --
> Mickaël Perraud
> Website | http://mikaelkael.fr
> Twitter | http://twitter.com/mikaelkael
> PGP key | http://mikaelkael.fr/mikaelkael.asc
>
>
>
> 2012/8/2 Enrico Zimuel <[hidden email]>
>
>> Hi all,
>>
>> i just wrote this post on devzone.zend.com on how to contribute to the
>> ZF2 documentation project:
>>
>> http://devzone.zend.com/2463/zf2-documentation-we-want-you/
>>
>> In the post I put evidence on the contribution process and how to use
>> the "Edit this document" button in the zf2.readthedocs.org site.
>>
>> Help us to spread this post, thanks!
>>
>> --
>> Enrico Zimuel
>> Senior PHP Engineer    | [hidden email]
>> Zend Framework Team    | http://framework.zend.com
>> Zend Technologies Ltd.
>> http://www.zend.com
>>
>


--
Enrico Zimuel
Senior PHP Engineer    | [hidden email]
Zend Framework Team    | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com



Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Mickael Perraud
In reply to this post by Mickael Perraud
Hi,

For point 2, I resolved it with text substitutions. I will push it to my proposal branch (https://github.com/mikaelkael/zf2-documentation/commits/translation-structure).

--
Mickaël Perraud

Website | http://mikaelkael.fr
Twitter | http://twitter.com/mikaelkael
PGP key | http://mikaelkael.fr/mikaelkael.asc



2012/8/6 Mickael Perraud <[hidden email]>
Hi Enrico,

I prefer the second solution because when an user read a translated documentation, he can understand that some parts are not translated but he want an complete and *up-to-date* documentation.

I want now to point out the difficulties of the translators with ZF1 documentation. To be clear, I am absolutely not against the migration from DocBook to reST but I will use the example of our work with DocBook to propose what we can do with reST.

Even if the translation can be a difficult work, maintain a translation is certainly the most difficult part of the work. Then we adopted some rules to simplify the work of maintainers:
 1) Remove the (manual.xml | index.rst) in each language => this limits the forgetting of a line when adding a file in the main documentation
 2) Put any translation outside the (manual.xml | index.rst) file => if we remove index.rst, we need to provide an alternative to translate title for example. We resolved it with XML entities with Docbook. The question is opened for reST
 3) Allow translators to easily detect modifications in English files => with ZF1, I created a translator tool (http://mikaelkael.dyndns.org/checker/) that can detect them with the help of a specific tag (exactly the same as PHP documentation). With Docbook and SVN it's a comment tag with the English revision number on which the translated file is based: "<!-- EN-Revision: 25000 -->". With reST and Git, it can be something like: ".. EN-Revision: 9a21dca" at the top/bottom of the file. Of course, with this, I will update the translator tool.

Next point is about http://readthedocs.org/. Currently they don't provide support for i18n (https://github.com/rtfd/readthedocs.org/issues/139) and even if they apply this PR (https://github.com/rtfd/readthedocs.org/pull/193), they will support the structure proposed by Sphinx (http://sphinx.pocoo.org/intl.html). Then a translation of ZF2 documentation can't be rendered by RTFD with the current structure. Of course we always have http://packages.zendframework.com/docs/latest/manual/en/ but it can be a good thing if we can render translated documentations.

Regards,
2012/8/6 Enrico Zimuel <[hidden email]>
Hi Mickael,

I see the problem for the translation of zf2-documentation.
Right now we don't have all the files translated and if you try to
compile the docs you will get errors (missing files).

I see two ways to manage this issue:

1) change the index.rst file (Table Of Contents) for each languages to
include only the translated files;

2) modify the Makefile to be able to copy the missing files from
/docs/languages/en and copy to the local languages throwing a message to
the user that say something like "The xxx file is missing from the
translation, I used the english file as temporary file"

I just discovered that you are already working on the second solution :)
https://github.com/mikaelkael/zf2-documentation/commit/9a21dca53966b03e8e32f666c601b8a21298ac06

That's great!
I think we can work on the second solution.
Folks any other ideas on that?

Regards,
Enrico Zimuel

On 08/06/2012 09:46 AM, Mickael Perraud wrote:
> Hi all,
>
> Is it allowed to begin translation? It seems not for the moment =>
> https://github.com/zendframework/zf2-documentation/pull/119
>
> I really don't understand comment like: "I know there is a bug, I know that
> you correct it, I simply don't want to apply your PR".
>
> Can you clarify this point, I don't want a battle each I will have a PR.
>
> Thanks in advance.
> --
> Mickaël Perraud
> Website | http://mikaelkael.fr
> Twitter | http://twitter.com/mikaelkael
> PGP key | http://mikaelkael.fr/mikaelkael.asc
>
>
>
> 2012/8/2 Enrico Zimuel <[hidden email]>
>
>> Hi all,
>>
>> i just wrote this post on devzone.zend.com on how to contribute to the
>> ZF2 documentation project:
>>
>> http://devzone.zend.com/2463/zf2-documentation-we-want-you/
>>
>> In the post I put evidence on the contribution process and how to use
>> the "Edit this document" button in the zf2.readthedocs.org site.
>>
>> Help us to spread this post, thanks!
>>
>> --
>> Enrico Zimuel
>> Senior PHP Engineer     | [hidden email]
>> Zend Framework Team     | http://framework.zend.com
>> Zend Technologies Ltd.
>> http://www.zend.com
>>
>


--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com


Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Enrico Zimuel-2
In reply to this post by Mickael Perraud
Hi Mickaël,

>
> I prefer the second solution because when an user read a translated
> documentation, he can understand that some parts are not translated but he
> want an complete and *up-to-date* documentation.

I agree, I think we should add some prefix text in the document that are
not translated and still in English, something like [ENG] followed by
the title. With that change we can easily check for docs to be translated.

>
> Even if the translation can be a difficult work, maintain a translation is
> certainly the most difficult part of the work. Then we adopted some rules
> to simplify the work of maintainers:

>  1) Remove the (manual.xml | index.rst) in each language => this limits the
> forgetting of a line when adding a file in the main documentation

The index.rst is in english and If we want to provide a full translation
we have to translate this file. That means we cannot remove it.

>  2) Put any translation outside the (manual.xml | index.rst) file => if we
> remove index.rst, we need to provide an alternative to translate title for
> example. We resolved it with XML entities with Docbook. The question is
> opened for reST

I think we can simplify that process using specific index.rst for each
language. The management, and the update, of this file is a
responsibility of the translator.

>  3) Allow translators to easily detect modifications in English files =>
> with ZF1, I created a translator tool (http://mikaelkael.dyndns.org/checker/)
> that can detect them with the help of a specific tag (exactly the same as
> PHP documentation). With Docbook and SVN it's a comment tag with the
> English revision number on which the translated file is based: "<!--
> EN-Revision: 25000 -->". With reST and Git, it can be something like: "..
> EN-Revision: 9a21dca" at the top/bottom of the file. Of course, with this,
> I will update the translator tool.

I think this is a very good tool and we should update it to work on reST
and Git.

>
> Next point is about http://readthedocs.org/. Currently they don't provide
> support for i18n (https://github.com/rtfd/readthedocs.org/issues/139) and
> even if they apply this PR (https://github.com/rtfd/readthedocs.org/pull/193),
> they will support the structure proposed by Sphinx (
> http://sphinx.pocoo.org/intl.html). Then a translation of ZF2 documentation
> can't be rendered by RTFD with the current structure. Of course we always
> have http://packages.zendframework.com/docs/latest/manual/en/ but it can be
> a good thing if we can render translated documentations.
>

This is an open question. I didn't use the internationalization solution
used by Sphinx because I think is not so good for a community project
like Zend Framework 2. I tried to translate the English docs in another
language using the .pot, .po and .mo files but at the end I had a couple
of giant files with all the sentences spread.
I think this is not so good to facilitate the work of translators. I
think is better to manage .rst file for each language.

That means right now we can use readthedocs.org only for the English
documentation. The only solution that I see right now is to create
different project in readthedocs.org for different languages and use
some "hack" to execute the Makefile for the specific language.

Regards,
Enrico Zimuel

>
>
> 2012/8/6 Enrico Zimuel <[hidden email]>
>
>> Hi Mickael,
>>
>> I see the problem for the translation of zf2-documentation.
>> Right now we don't have all the files translated and if you try to
>> compile the docs you will get errors (missing files).
>>
>> I see two ways to manage this issue:
>>
>> 1) change the index.rst file (Table Of Contents) for each languages to
>> include only the translated files;
>>
>> 2) modify the Makefile to be able to copy the missing files from
>> /docs/languages/en and copy to the local languages throwing a message to
>> the user that say something like "The xxx file is missing from the
>> translation, I used the english file as temporary file"
>>
>> I just discovered that you are already working on the second solution :)
>>
>> https://github.com/mikaelkael/zf2-documentation/commit/9a21dca53966b03e8e32f666c601b8a21298ac06
>>
>> That's great!
>> I think we can work on the second solution.
>> Folks any other ideas on that?
>>
>> Regards,
>> Enrico Zimuel
>>
>> On 08/06/2012 09:46 AM, Mickael Perraud wrote:
>>> Hi all,
>>>
>>> Is it allowed to begin translation? It seems not for the moment =>
>>> https://github.com/zendframework/zf2-documentation/pull/119
>>>
>>> I really don't understand comment like: "I know there is a bug, I know
>> that
>>> you correct it, I simply don't want to apply your PR".
>>>
>>> Can you clarify this point, I don't want a battle each I will have a PR.
>>>
>>> Thanks in advance.
>>> --
>>> Mickaël Perraud
>>> Website | http://mikaelkael.fr
>>> Twitter | http://twitter.com/mikaelkael
>>> PGP key | http://mikaelkael.fr/mikaelkael.asc
>>>
>>>
>>>
>>> 2012/8/2 Enrico Zimuel <[hidden email]>
>>>
>>>> Hi all,
>>>>
>>>> i just wrote this post on devzone.zend.com on how to contribute to the
>>>> ZF2 documentation project:
>>>>
>>>> http://devzone.zend.com/2463/zf2-documentation-we-want-you/
>>>>
>>>> In the post I put evidence on the contribution process and how to use
>>>> the "Edit this document" button in the zf2.readthedocs.org site.
>>>>
>>>> Help us to spread this post, thanks!
>>>>
>>>> --
>>>> Enrico Zimuel
>>>> Senior PHP Engineer     | [hidden email]
>>>> Zend Framework Team     | http://framework.zend.com
>>>> Zend Technologies Ltd.
>>>> http://www.zend.com
>>>>
>>>
>>
>>
>> --
>> Enrico Zimuel
>> Senior PHP Engineer     | [hidden email]
>> Zend Framework Team     | http://framework.zend.com
>> Zend Technologies Ltd.
>> http://www.zend.com
>>
>


--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com
Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Artur Bodera
On Tue, Aug 7, 2012 at 12:14 PM, Enrico Zimuel <[hidden email]> wrote:

That means right now we can use readthedocs.org only for the English
documentation. The only solution that I see right now is to create
different project in readthedocs.org for different languages and use
some "hack" to execute the Makefile for the specific language.


Why not work on TOC / chapter level with that ?

We could split the whole documentation to EN, DE, FR, main chapters... and 
current chapters will be sub-chapters beneath that. This way it'd be trivial to 
import the whole thing into RTD.org and we'd still be able to have the github
goodness we currently have.

-- 
      __
     /.)\   +48 695 600 936
     \(./   [hidden email]




Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Mickael Perraud
In reply to this post by Enrico Zimuel-2
>>  1) Remove the (manual.xml | index.rst) in each language => this limits the
>> forgetting of a line when adding a file in the main documentation

> The index.rst is in english and If we want to provide a full translation
> we have to translate this file. That means we cannot remove it.

It's not true ;) see https://github.com/mikaelkael/zf2-documentation/commit/fa0778dc8d32cce353767aa4a2880a944895df89
--
Mickaël Perraud

Website | http://mikaelkael.fr
Twitter | http://twitter.com/mikaelkael
PGP key | http://mikaelkael.fr/mikaelkael.asc



2012/8/7 Enrico Zimuel <[hidden email]>
Hi Mickaël,

>
> I prefer the second solution because when an user read a translated
> documentation, he can understand that some parts are not translated but he
> want an complete and *up-to-date* documentation.

I agree, I think we should add some prefix text in the document that are
not translated and still in English, something like [ENG] followed by
the title. With that change we can easily check for docs to be translated.

>
> Even if the translation can be a difficult work, maintain a translation is
> certainly the most difficult part of the work. Then we adopted some rules
> to simplify the work of maintainers:

>  1) Remove the (manual.xml | index.rst) in each language => this limits the
> forgetting of a line when adding a file in the main documentation

The index.rst is in english and If we want to provide a full translation
we have to translate this file. That means we cannot remove it.

>  2) Put any translation outside the (manual.xml | index.rst) file => if we
> remove index.rst, we need to provide an alternative to translate title for
> example. We resolved it with XML entities with Docbook. The question is
> opened for reST

I think we can simplify that process using specific index.rst for each
language. The management, and the update, of this file is a
responsibility of the translator.

>  3) Allow translators to easily detect modifications in English files =>
> with ZF1, I created a translator tool (http://mikaelkael.dyndns.org/checker/)
> that can detect them with the help of a specific tag (exactly the same as
> PHP documentation). With Docbook and SVN it's a comment tag with the
> English revision number on which the translated file is based: "<!--
> EN-Revision: 25000 -->". With reST and Git, it can be something like: "..
> EN-Revision: 9a21dca" at the top/bottom of the file. Of course, with this,
> I will update the translator tool.

I think this is a very good tool and we should update it to work on reST
and Git.

>
> Next point is about http://readthedocs.org/. Currently they don't provide
> support for i18n (https://github.com/rtfd/readthedocs.org/issues/139) and
> even if they apply this PR (https://github.com/rtfd/readthedocs.org/pull/193),
> they will support the structure proposed by Sphinx (
> http://sphinx.pocoo.org/intl.html). Then a translation of ZF2 documentation
> can't be rendered by RTFD with the current structure. Of course we always
> have http://packages.zendframework.com/docs/latest/manual/en/ but it can be
> a good thing if we can render translated documentations.
>

This is an open question. I didn't use the internationalization solution
used by Sphinx because I think is not so good for a community project
like Zend Framework 2. I tried to translate the English docs in another
language using the .pot, .po and .mo files but at the end I had a couple
of giant files with all the sentences spread.
I think this is not so good to facilitate the work of translators. I
think is better to manage .rst file for each language.

That means right now we can use readthedocs.org only for the English
documentation. The only solution that I see right now is to create
different project in readthedocs.org for different languages and use
some "hack" to execute the Makefile for the specific language.

Regards,
Enrico Zimuel

>
>
> 2012/8/6 Enrico Zimuel <[hidden email]>
>
>> Hi Mickael,
>>
>> I see the problem for the translation of zf2-documentation.
>> Right now we don't have all the files translated and if you try to
>> compile the docs you will get errors (missing files).
>>
>> I see two ways to manage this issue:
>>
>> 1) change the index.rst file (Table Of Contents) for each languages to
>> include only the translated files;
>>
>> 2) modify the Makefile to be able to copy the missing files from
>> /docs/languages/en and copy to the local languages throwing a message to
>> the user that say something like "The xxx file is missing from the
>> translation, I used the english file as temporary file"
>>
>> I just discovered that you are already working on the second solution :)
>>
>> https://github.com/mikaelkael/zf2-documentation/commit/9a21dca53966b03e8e32f666c601b8a21298ac06
>>
>> That's great!
>> I think we can work on the second solution.
>> Folks any other ideas on that?
>>
>> Regards,
>> Enrico Zimuel
>>
>> On 08/06/2012 09:46 AM, Mickael Perraud wrote:
>>> Hi all,
>>>
>>> Is it allowed to begin translation? It seems not for the moment =>
>>> https://github.com/zendframework/zf2-documentation/pull/119
>>>
>>> I really don't understand comment like: "I know there is a bug, I know
>> that
>>> you correct it, I simply don't want to apply your PR".
>>>
>>> Can you clarify this point, I don't want a battle each I will have a PR.
>>>
>>> Thanks in advance.
>>> --
>>> Mickaël Perraud
>>> Website | http://mikaelkael.fr
>>> Twitter | http://twitter.com/mikaelkael
>>> PGP key | http://mikaelkael.fr/mikaelkael.asc
>>>
>>>
>>>
>>> 2012/8/2 Enrico Zimuel <[hidden email]>
>>>
>>>> Hi all,
>>>>
>>>> i just wrote this post on devzone.zend.com on how to contribute to the
>>>> ZF2 documentation project:
>>>>
>>>> http://devzone.zend.com/2463/zf2-documentation-we-want-you/
>>>>
>>>> In the post I put evidence on the contribution process and how to use
>>>> the "Edit this document" button in the zf2.readthedocs.org site.
>>>>
>>>> Help us to spread this post, thanks!
>>>>
>>>> --
>>>> Enrico Zimuel
>>>> Senior PHP Engineer     | [hidden email]
>>>> Zend Framework Team     | http://framework.zend.com
>>>> Zend Technologies Ltd.
>>>> http://www.zend.com
>>>>
>>>
>>
>>
>> --
>> Enrico Zimuel
>> Senior PHP Engineer     | [hidden email]
>> Zend Framework Team     | http://framework.zend.com
>> Zend Technologies Ltd.
>> http://www.zend.com
>>
>


--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com

Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

Mickael Perraud
In reply to this post by Enrico Zimuel-2

> Next point is about http://readthedocs.org/. Currently they don't provide
> support for i18n (https://github.com/rtfd/readthedocs.org/issues/139) and
> even if they apply this PR (https://github.com/rtfd/readthedocs.org/pull/193),
> they will support the structure proposed by Sphinx (
> http://sphinx.pocoo.org/intl.html). Then a translation of ZF2 documentation
> can't be rendered by RTFD with the current structure. Of course we always
> have http://packages.zendframework.com/docs/latest/manual/en/ but it can be
> a good thing if we can render translated documentations.
>

This is an open question. I didn't use the internationalization solution
used by Sphinx because I think is not so good for a community project
like Zend Framework 2. I tried to translate the English docs in another
language using the .pot, .po and .mo files but at the end I had a couple
of giant files with all the sentences spread.
I think this is not so good to facilitate the work of translators. I
think is better to manage .rst file for each language.

I completely agree on this point.
--
Mickaël Perraud

Website | http://mikaelkael.fr
Twitter | http://twitter.com/mikaelkael
PGP key | http://mikaelkael.fr/mikaelkael.asc

Reply | Threaded
Open this post in threaded view
|

Re: How to contribute to ZF2 documentation project

jimmybrion
This post has NOT been accepted by the mailing list yet.
In reply to this post by Enrico Zimuel-2
Thank You Enrico

We will check it out and will contribute to Zend project.

Thanks,
Jimmy
Zend Developer