Hi, While I 100% agree with @Xingcan that we should try to avoid adding extra burden for contributors, at the very least, creating JIRA issues for adding missing Chinese / English document updates must be done.
In the past, even with English documentation only, we already had the problem of merging new features / API changes without updating the document within the same contribution. Over time, these missing document updates pile up and are only ever fixed near the end of our release testing phases. It would be much better if documentation for new features or changes to the API are documented upfront and available already at the release testing phase. Not only would these open up more opportunities for non-developers to try out the release, but also more eyes to help proofread new documents before officially releasing. I would like to see that this situation of "lagging documentation updates until release" improves at the same time while we start introducing Chinese docs, otherwise I think the situation will only deteriorate with the new complications. While I'm still leaning more towards my previous suggestion to strictly require that both Chinese / English documents are updated in a single contribution if either side is touched (), I'm willing to withdraw that, given how it will definitely add more burden for contributors and lengthens the contribution process (i.e. PRs being blocked on something out of their control due to language barriers). So, to wrap up, I propose the following action points (actually most of which already mentioned earlier by other people): - Adjust our PR review bot to include a "updated required English documentation" & "opened a JIRA for Chinese documentation translation sync" checks. A PR should not be merged without these checks being approved. - Add a "zh-doc" label (names TBD) to our JIRA, which should be tagged on Chinese documentation sync JIRAs opened in the previous step. - Educate and encourage Chinese-speaking developers to search for these labels in our contribution guidelines [1] & project WIKI [2]. Cheers, Gordon [1] https://flink.apache.org/contribute-documentation.html [2] https://cwiki.apache.org/confluence/display/FLINK/Pull+Request+Management On Tue, Feb 12, 2019 at 10:06 AM Rong Rong <walter...@gmail.com> wrote: > Hi all, > > Thanks @Jark for creating the translation terminology document! I think the > idea of keeping some of the terminologies untranslated and keeping such > document in place is absolutely good. > I actually share the same concern with @Shaoxuan regarding the discrepancy > getting larger. The dilemma is always been whether we block a merge because > document translation, or create a follow up JIRA. Either way this will be > extra effort on Chinese-speaking contributors, however the former creates > less discrepancies. > > I actually agree with @Xingcan that translation should not create extra > burden, and better adding Chinese doc translation guidelines for both > contributors and reviewers. For example, Kylin actually have a specific > section for multi-language support contribution[1]. It might be a good > starting point for a more well-rounded guideline? > > Best, > Rong > > [1] http://kylin.apache.org/development/howto_docs.html > > On Mon, Feb 11, 2019 at 8:04 AM Xingcan Cui <xingc...@gmail.com> wrote: > > > Hi, > > > > Thank you for working on this. > > > > I think assigning pages to someones and synchronizing them regularly may > > be a better idea. > > > > 1. We encourage contributors who are familiar with Chinese and would like > > to do the translation to provide Chinese doc updates in sync, but should > > not add extra burden (even like creating translation JIRA issues) to > others. > > 2. Designated people could merge minor updates into one and ensure > > translation quality. > > 3. It would be better to add the Chinese doc translation step into the > > reviewing checklist and provide some rules for the synchronization work > > (e.g., the docs must be synced when a new version is to be released). > > > > Best, > > Xingcan > > > > > On Feb 11, 2019, at 6:23 AM, Jark Wu <imj...@gmail.com> wrote: > > > > > > Hi Shaoxuan, > > > > > > Thank you for your feedback. > > > > > > If the author is not familiar with Chinese, he/she should create a > > > translation JIRA before the pull request is merged in. > > > The created JIRA can be attached a "chinese-translation" tag so that it > > can > > > be searched easily. Then a Chinese contributor can take this JIRA and > > > translate it after the original JIRA is merged. > > > In order to make this work, we will add a checklist to the review-bot > to > > > check whether a translation JIRA is created or both English/Chinese > docs > > > are updated. > > > > > > The changes to the contribute process is included in the proposal doc: > > > > > > https://docs.google.com/document/d/1R1-uDq-KawLB8afQYrczfcoQHjjIhq6tvUksxrfhBl0/edit#heading=h.7yn7issnkrey > > > > > > Best, > > > Jark > > > > > > > > > On Mon, 11 Feb 2019 at 15:20, Shaoxuan Wang <wshaox...@gmail.com> > wrote: > > > > > >> Thanks for spending efforts to build a Flink web in Chinese, everyone. > > >> > > >> Good job, Jark! > > >> > > >> This looks look to me. I have only one concern about the > > synchronization of > > >> the English and Chinese website. We can not expect the author of the > > >> English doc to produce Chinese doc at the same time. If no one follows > > up > > >> on the changes in English documents, it will not take long for the > > >> difference between English and Chinese docs to become larger and > > larger. I > > >> suggest we should assign the owners to the Chinese web, say 1-2 people > > (we > > >> can have more people, then do monthly rotate). They regularly (weekly > > >> or monthly) catch the new changes in English doc and > > synchronize/translate > > >> them to the Chinese doc. > > >> > > >> Regards, > > >> Shaoxuan > > >> > > >> > > >> On Mon, Feb 4, 2019 at 1:23 PM Jark Wu <imj...@gmail.com> wrote: > > >> > > >>> Hi all, > > >>> > > >>> I have drafted the proposal: > > >>> > > >>> > > >> > > > https://docs.google.com/document/d/1R1-uDq-KawLB8afQYrczfcoQHjjIhq6tvUksxrfhBl0/edit# > > >>> Please feel free to give any feedbacks! > > >>> > > >>> I have also created a prototype to integrate Chinese for flink-web, > > here > > >> is > > >>> the branch: https://github.com/wuchong/flink-web/tree/multi-language > > >>> > > >>> @Fabian Hueske <fhue...@gmail.com> +1 to start contribute flink-web > > >>> first. > > >>> > > >>> @Gordon That's a good idea to add the document checklist to the > review > > >>> process. I have included this in the proposal. What do you think > > @Robert > > >>> Metzger <rmetz...@apache.org> @Fabian Hueske <fhue...@gmail.com> ? > > >>> > > >>> Btw, Happy Chinese New Year! :) > > >>> > > >>> Cheers, Jark > > >>> > > >>> > > >>> On Fri, 1 Feb 2019 at 18:22, Tzu-Li (Gordon) Tai < > tzuli...@apache.org> > > >>> wrote: > > >>> > > >>>> Hi, > > >>>> > > >>>> Great seeing efforts in pushing this forward, Jark! > > >>>> > > >>>> A bit late in the party here, but I just want to also point out > that: > > >>>> > > >>>> - +1 to https://flink.apache.org/zh/ as the website address > > >>>> - Add to the contribution checklist in PRs that both English / > Chinese > > >>> docs > > >>>> have been updated accordingly. > > >>>> > > >>>> I want to point out that, if a contribution touches either the > English > > >> or > > >>>> Chinese documentation, then both sides should be updated before the > > >>>> contribution can be merged. > > >>>> Otherwise, in the long run, it'll be very hard to keep track which > > >> parts > > >>> of > > >>>> the documentation requires update. > > >>>> > > >>>> For this to work, we might need a list of known Chinese-speaking > > >>>> contributors who would be willing to work on the Chinese docs > > available > > >>>> somewhere (maybe in the project community Wiki?), so that an English > > >>>> contributor knows who they can reach out to for helping with the > > >>>> translation. > > >>>> The same goes for the other way around. > > >>>> > > >>>> Cheers, > > >>>> Gordon > > >>>> > > >>>> On Fri, Feb 1, 2019 at 5:39 PM Fabian Hueske <fhue...@gmail.com> > > >> wrote: > > >>>> > > >>>>> Hi Jark, > > >>>>> > > >>>>> Thanks for working out a plan to integrate the Chinese translation! > > >>>>> > > >>>>> I would propose to first contribute and integrate the Chinese > version > > >>> of > > >>>>> the main page (flink.apache.org). > > >>>>> It is much smaller than the docs and a smaller scope might help to > > >> find > > >>>>> tricks to ease the integration of the documentation. > > >>>>> > > >>>>> Looking forward to the proposal, > > >>>>> Fabian > > >>>>> > > >>>>> > > >>>>> > > >>>>> > > >>>>> > > >>>>> Am Di., 29. Jan. 2019 um 13:37 Uhr schrieb Jark Wu < > imj...@gmail.com > > >>> : > > >>>>> > > >>>>>> Hi, > > >>>>>> > > >>>>>> Thank you all for welcoming this proposal. > > >>>>>> I will draft a detailed proposal about how to do contribute it > step > > >>> by > > >>>>> step > > >>>>>> in the next few days, and create umbrella JIRA once the proposal > is > > >>>>>> accepted. > > >>>>>> > > >>>>>> @Fabian @JIngcheng Regarding the name, I'm fine with > > >>>>>> https://flink.apache.org/zh/. > > >>>>>> > > >>>>>> @Yun Tang Thanks for pointing Alluxio out as a reference. I agree > > >>> with > > >>>>> that > > >>>>>> reviewing Chinese documentation is not easy for the community. > > >>>>>> But I think this wouldn't be a big problem as the community > already > > >>> has > > >>>>>> many Chinese-speaking committers and more Chinese contributors are > > >>>>> joining > > >>>>>> in. > > >>>>>> > > >>>>>> @Dian Fu Adding a step to the review process is a good idea! > > >>>>>> Maybe we can automatically add an item of "Chinese document sync" > > >>> when > > >>>>> the > > >>>>>> document is modified with the help of the newly introduced > > >>> review-bot. > > >>>>>> > > >>>>>> Hi @Jörn Franke > > >>>>>>> Keep also in mind the other direction eg a new/modified version > > >> of > > >>>> the > > >>>>>> Chinese documentation needs to be reflected in the English one. > > >>>>>> I think we should always modify English doc first, and then > > >> translate > > >>>> the > > >>>>>> changes to Chinese document. > > >>>>>> > > >>>>>> Hi @Chesnay > > >>>>>>> Is the build-system for flink-china.org identical to flink-web? > > >>>>>> The build-system of flink-china.org is wrote by Yadong ( > > >>>>>> vthink...@gmail.com) > > >>>>>> which is not using Jekyll. You can access the code of > > >>> flink-china.org > > >>>>>> via: > > >>>>>> https://github.com/flink-china/doc > > >>>>>> > > >>>>>> Best, > > >>>>>> Jark > > >>>>>> > > >>>>>> On Tue, 29 Jan 2019 at 18:21, Chesnay Schepler < > ches...@apache.org > > >>> > > >>>>> wrote: > > >>>>>> > > >>>>>>> Is the build-system for flink-china.org identical to flink-web? > > >>>>>>> > > >>>>>>> On 28.01.2019 12:48, Jark Wu wrote: > > >>>>>>>> Hi all, > > >>>>>>>> > > >>>>>>>> In the past year, the Chinese community is working on building > > >> a > > >>>>>> Chinese > > >>>>>>>> translated Flink website (http://flink.apache.org) and > > >>> documents ( > > >>>>>>>> http://ci.apache.org/projects/flink/flink-docs-master/) in > > >> order > > >>>> to > > >>>>>> help > > >>>>>>>> Chinese speaking users. This is http://flink-china.org and it > > >>> has > > >>>>>>> received > > >>>>>>>> a lot of praise since online. > > >>>>>>>> > > >>>>>>>> In order to follow the Apache Way and grow Apache Flink > > >>> community, > > >>>> we > > >>>>>>> want > > >>>>>>>> to contribute it to Apache Flink. It contains two parts to > > >>>>> contribute: > > >>>>>>>> (1) the Chinese translated version of the Flink website > > >>>>>>>> (2) the Chinese translated version of the Flink documentation. > > >>>>>>>> > > >>>>>>>> But there are some questions are up to discuss: > > >>>>>>>> > > >>>>>>>> ## The Address of the translated version > > >>>>>>>> > > >>>>>>>> I think we can add a Chinese channel on official flink website, > > >>>> such > > >>>>>> as " > > >>>>>>>> https://flink.apache.org/cn/";, which is similar as " > > >>>>>>>> http://kylin.apache.org/cn/";. And use " > > >>>>>>>> https://ci.apache.org/projects/flink/flink-docs-zh-master/"; to > > >>> put > > >>>>> the > > >>>>>>>> Chinese translated docs. > > >>>>>>>> > > >>>>>>>> ## Add a link to the translated version > > >>>>>>>> > > >>>>>>>> It would be great if we can add links to each other in both > > >>> Chinese > > >>>>>>> version > > >>>>>>>> and English version. For example, we can add a link to the > > >>>> translated > > >>>>>>>> website on the sidebar of the Flink website. We can also add a > > >>>>> dropdown > > >>>>>>>> button for the Chinese document version under the "Pick Docs > > >>>> Version" > > >>>>>> in > > >>>>>>>> Flink document. > > >>>>>>>> > > >>>>>>>> ## How to contribute the translation in a long term > > >>>>>>>> > > >>>>>>>> This is a more important problem. Because translation is a huge > > >>> and > > >>>>>>>> long-term work. We need a healthy mechanism to ensure the > > >>>>>> sustainability > > >>>>>>> of > > >>>>>>>> contributions and the quality of translations. > > >>>>>>>> > > >>>>>>>> I would suggest to put the Chinese version document in flink > > >> repo > > >>>>> (such > > >>>>>>> as > > >>>>>>>> "doc-zh" folder) and update with the master. Once we modify the > > >>>>> English > > >>>>>>>> doc, we have to update the Chinese doc together, or create a > > >> JIRA > > >>>>>>> (contains > > >>>>>>>> git commit id refer to the English modification) to do that. > > >> This > > >>>>> will > > >>>>>>>> increase some workload when we update the doc. But this will > > >> keep > > >>>> the > > >>>>>>>> Chinese doc up to date. We can attract more Chinese > > >> contributors > > >>> to > > >>>>>> help > > >>>>>>>> build the doc. And the modification is small enough and easy to > > >>>>> review. > > >>>>>>>> > > >>>>>>>> Maybe there is a better solution and we can also learn how the > > >>>> other > > >>>>>>>> projects do it. > > >>>>>>>> > > >>>>>>>> Any feedbacks are welcome! > > >>>>>>>> > > >>>>>>>> Best, > > >>>>>>>> Jark Wu > > >>>>>>>> > > >>>>>>> > > >>>>>>> > > >>>>>> > > >>>>> > > >>>> > > >>> > > >> > > > > >
