Re: [PATCH v2 1/2] docs: doc-guide: add a guide for translators

[Jonathan Corbet]

Daniel Pereira <danielmaraboo@xxxxxxxxx> writes:

> The documentation has seven translations, but nothing in the English
> documentation explains how to contribute to them.  The only guide that
> exists, Documentation/translations/zh_CN/how-to.rst, is written in
> Chinese and covers the zh_CN translation only.
>
> As a result, the same problems come up over and over in the review of
> translation patches: labels and citations copied from the original,
> which are global in Sphinx and collide with the English ones; partial
> builds with SPHINXDIRS that hide those collisions; lines over 80
> columns; translations not added to any toctree; missing commit
> descriptions, tags separated by blank lines, HTML email rejected by the
> lists, and the documentation maintainer left out of the recipients.
>
> Add Documentation/doc-guide/translations.rst, a guide that covers the
> whole workflow of a translation:

So I finally managed to read through this ... sorry for taking so long.
Thanks for putting this together, I think it will be useful.

I don't have a lot of comments beyond what others have particularly
said.  I would definitely echo Federico's suggestion about not
duplicating the material found in the other process documents.  Length
and verbosity makes documents less approachable, so anything you can do
to make this one more concise will help.  I'd just tell people to read
and understand the relevant process documents.

One little thing I might add: anybody who spends time with our
documentation will surely find things that can be improved in the
original as well.  I'd encourage all translators to send fixes to the
English versions when they find these things; that will make it better
for everybody.

Thanks,

jon