Hi Gordon, I totally agree with your proposal.
A minor comment: "updated required English documentation" should be "updated required Chinese documentation" ? Btw, I like the "zh-doc" label! Regards, Jark On Tue, 12 Feb 2019 at 14:48, Tzu-Li (Gordon) Tai <tzuli...@apache.org> wrote: > 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 > > > >>>>>>>> > > > >>>>>>> > > > >>>>>>> > > > >>>>>> > > > >>>>> > > > >>>> > > > >>> > > > >> > > > > > > > > >
