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

[Weijie Yuan]

Daniel Pereira <danielmaraboo@xxxxxxxxx> writes:

> (Resending to the list: my previous reply went only to Dongliang.)
> 
> On Sun, Oct 25, 2026 at 11:22 +0800, Dongliang Mu wrote:
> > Good job. I will quickly verify them and send a patch to move them.
> 
> Thanks. To avoid overlap, could you confirm which languages your patch
> covers? I understand zh_CN, and that zh_TW is already handled by
> Chen-Yu's series. That leaves:
> 
> - sp_SP: process/magic-number.rst and wrappers/memory-barriers.rst;
> - the .txt files in ja_JP and ko_KR (stable_api_nonsense.txt and
> stable_kernel_rules.txt), which I think are for their maintainers
> to convert or drop.
> 
> > It seems the original English documentation moves fast. I would
> > write a script or skill to check this relationship maybe daily or
> > weekly.
> 
> A periodic check like that would be useful, especially once the guide
> states the path mirroring as a rule.
> 
> For v3 of the guide, this is what I plan, based on the discussion so
> far:
> 
> - state the path mirroring as a rule for translations of English
> documents, and exempt documents that exist only in a translation,
> such as a glossary or a language-specific how-to (Chen-Yu);
> - describe ":Original:" as optional, and not needed when the path
> mirrors the original, instead of showing it in the header example
> (Jani, Weijie, Dongliang);
> - drop the generic parts of the sections on writing documentation
> and sending patches, and link to doc-guide/sphinx.rst and
> process/submitting-patches.rst instead, keeping only the points
> specific to translations (Federico).

Thanks for your effort above, looks good to me in general.

> Federico, I did not see an answer to my last message about this last
> point. Is keeping those short translation-specific notes fine with you?

Yup, I agree with Federico that for general guidelines, new contributors
should refer to the more authoritative ones. (unless there are some
translation-specific parts needs to be stressed) This way, if these
authoritatice ones change, we don't need to bother to sync them.

However, contrary to this, I would like to know if it is necessary for
us to promote b4 a little bit more here. (b4 is already mentioned in
SubmittingPatches.)

I'm not sure how many times such situations have occurred: new
contributors send patches with duplicate title lines and messy threads,
making it difficult to search through them on lore archive; there was a
thread breakage due to a problem with their email server..

These are the problems that the new faces on the list are likely to
encounter, but B4 (b4 prep) can simplify this process for new
contributors. [example trimmed for brevity]

And yes, once these procedures are familiarized with, everyone can work
according to their own preferences. However, just like how Konstantin
said: "if you're just starting out, and you don't already have a
workflow, hopefully this(b4) gives a good workflow for you to try and
follow."

Comments are appreciated. Thanks!