You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flink.apache.org by Aljoscha Krettek <al...@apache.org> on 2020/02/14 15:39:29 UTC
[ANNOUNCE] New Documentation Style Guide
Hi Everyone,
we just merged a new style guide for documentation writing:
https://flink.apache.org/contributing/docs-style.html.
Anyone who is writing documentation or is planning to do so should check
this out. Please open a Jira Issue or respond here if you have any
comments or questions.
Some of the most important points in the style guide are:
- We should use direct language and address the reader as you instead
of passive constructions. Please read the guide if you want to
understand what this means.
- We should use "alert blocks" instead of simple inline alert tags.
Again, please refer to the guide to see what this means exactly if
you're not sure.
There's plenty more and some interesting links about
technical/documentation writing as well.
Best,
Aljoscha
Re: [ANNOUNCE] New Documentation Style Guide
Posted by Hequn Cheng <he...@apache.org>.
Thanks Marta and Aljoscha for the detailed document! This is very helpful.
Best,
Hequn
On Mon, Feb 17, 2020 at 9:07 PM Aljoscha Krettek <al...@apache.org>
wrote:
> Just to be clear: I didn't write this style guide. Marta (in cc) wrote
> this, I just finally merged it.
>
> Best,
> Aljoscha
>
> On 17.02.20 11:45, jincheng sun wrote:
> > Thanks for this great job Aljoscha!
> >
> > Best,
> > Jincheng
> >
> >
> >
> > Yu Li <ca...@gmail.com> 于2020年2月17日周一 下午6:42写道：
> >
> >> I think the guide itself is a great example of the new style! Thanks for
> >> driving this, Aljoscha!
> >>
> >> Best Regards,
> >> Yu
> >>
> >>
> >> On Mon, 17 Feb 2020 at 16:44, Becket Qin <be...@gmail.com> wrote:
> >>
> >>> The guideline is very practical! I like it! Thanks for putting it
> >> together,
> >>> Aljoscha.
> >>>
> >>> Jiangjie (Becket) Qin
> >>>
> >>> On Mon, Feb 17, 2020 at 10:04 AM Xintong Song <to...@gmail.com>
> >>> wrote:
> >>>
> >>>> Thanks for the summary!
> >>>>
> >>>> I've read through the guidelines and found it very helpful. Many of
> the
> >>>> questions I had while working on the 1.10 docs the answer can be found
> >> in
> >>>> the guideline. And it also inspires me with questions I have never
> >>> thought
> >>>> of, especially the language style part.
> >>>>
> >>>> Thank you~
> >>>>
> >>>> Xintong Song
> >>>>
> >>>>
> >>>>
> >>>> On Sun, Feb 16, 2020 at 12:55 AM Zhijiang
> >>>> <wa...@aliyun.com.invalid> wrote:
> >>>>
> >>>>> Thanks for bringing this great and valuable document.
> >>>>>
> >>>>> I read through the document and was inspired especially by some
> >>> sections
> >>>>> in "Voice and Tone" and "General Guiding Principles".
> >>>>> I think it is not only helpful for writing Flink documents, but
> also
> >>>>> provides guideline/benefit for other writings.
> >>>>> It also reminded me to extend the Flink glossary if necessary.
> >>>>>
> >>>>> Best,
> >>>>> Zhijiang
> >>>>>
> >>>>>
> >>>>> ------------------------------------------------------------------
> >>>>> From:Jingsong Li <ji...@gmail.com>
> >>>>> Send Time:2020 Feb. 15 (Sat.) 23:21
> >>>>> To:dev <de...@flink.apache.org>
> >>>>> Subject:Re: [ANNOUNCE] New Documentation Style Guide
> >>>>>
> >>>>> Thank for the great work,
> >>>>>
> >>>>> In 1.10, I have modified and reviewed some documents. In that
> >> process,
> >>>>> sometimes there is some confusion, how to write is the standard. How
> >> to
> >>>>> write is correct to the users.
> >>>>> Docs style now tells me. Learned a lot.
> >>>>>
> >>>>> Best,
> >>>>> Jingsong Lee
> >>>>>
> >>>>> On Sat, Feb 15, 2020 at 10:00 PM Dian Fu <di...@gmail.com>
> >>> wrote:
> >>>>>
> >>>>>> Thanks for the great work! This is very helpful to keep the
> >>>> documentation
> >>>>>> style consistent across the whole project. It's also very helpful
> >> for
> >>>>>> non-native English contributors like me.
> >>>>>>
> >>>>>>> 在 2020年2月15日，下午3:42，Jark Wu <im...@gmail.com> 写道：
> >>>>>>>
> >>>>>>> Great summary! Thanks for adding the translation specification in
> >>> it.
> >>>>>>> I learned a lot from the guide.
> >>>>>>>
> >>>>>>> Best,
> >>>>>>> Jark
> >>>>>>>
> >>>>>>> On Fri, 14 Feb 2020 at 23:39, Aljoscha Krettek <
> >>> aljoscha@apache.org>
> >>>>>> wrote:
> >>>>>>>
> >>>>>>>> Hi Everyone,
> >>>>>>>>
> >>>>>>>> we just merged a new style guide for documentation writing:
> >>>>>>>> https://flink.apache.org/contributing/docs-style.html.
> >>>>>>>>
> >>>>>>>> Anyone who is writing documentation or is planning to do so
> >> should
> >>>>> check
> >>>>>>>> this out. Please open a Jira Issue or respond here if you have
> >> any
> >>>>>>>> comments or questions.
> >>>>>>>>
> >>>>>>>> Some of the most important points in the style guide are:
> >>>>>>>>
> >>>>>>>> - We should use direct language and address the reader as you
> >>>> instead
> >>>>>>>> of passive constructions. Please read the guide if you want to
> >>>>>>>> understand what this means.
> >>>>>>>>
> >>>>>>>> - We should use "alert blocks" instead of simple inline alert
> >>> tags.
> >>>>>>>> Again, please refer to the guide to see what this means exactly
> >> if
> >>>>>>>> you're not sure.
> >>>>>>>>
> >>>>>>>> There's plenty more and some interesting links about
> >>>>>>>> technical/documentation writing as well.
> >>>>>>>>
> >>>>>>>> Best,
> >>>>>>>> Aljoscha
> >>>>>>>>
> >>>>>>
> >>>>>>
> >>>>>
> >>>>> --
> >>>>> Best, Jingsong Lee
> >>>>>
> >>>>>
> >>>>
> >>>
> >>
> >
>
Re: [ANNOUNCE] New Documentation Style Guide
Posted by Aljoscha Krettek <al...@apache.org>.
Just to be clear: I didn't write this style guide. Marta (in cc) wrote
this, I just finally merged it.
Best,
Aljoscha
On 17.02.20 11:45, jincheng sun wrote:
> Thanks for this great job Aljoscha!
>
> Best,
> Jincheng
>
>
>
> Yu Li <ca...@gmail.com> 于2020年2月17日周一 下午6:42写道：
>
>> I think the guide itself is a great example of the new style! Thanks for
>> driving this, Aljoscha!
>>
>> Best Regards,
>> Yu
>>
>>
>> On Mon, 17 Feb 2020 at 16:44, Becket Qin <be...@gmail.com> wrote:
>>
>>> The guideline is very practical! I like it! Thanks for putting it
>> together,
>>> Aljoscha.
>>>
>>> Jiangjie (Becket) Qin
>>>
>>> On Mon, Feb 17, 2020 at 10:04 AM Xintong Song <to...@gmail.com>
>>> wrote:
>>>
>>>> Thanks for the summary!
>>>>
>>>> I've read through the guidelines and found it very helpful. Many of the
>>>> questions I had while working on the 1.10 docs the answer can be found
>> in
>>>> the guideline. And it also inspires me with questions I have never
>>> thought
>>>> of, especially the language style part.
>>>>
>>>> Thank you~
>>>>
>>>> Xintong Song
>>>>
>>>>
>>>>
>>>> On Sun, Feb 16, 2020 at 12:55 AM Zhijiang
>>>> <wa...@aliyun.com.invalid> wrote:
>>>>
>>>>> Thanks for bringing this great and valuable document.
>>>>>
>>>>> I read through the document and was inspired especially by some
>>> sections
>>>>> in "Voice and Tone" and "General Guiding Principles".
>>>>> I think it is not only helpful for writing Flink documents, but also
>>>>> provides guideline/benefit for other writings.
>>>>> It also reminded me to extend the Flink glossary if necessary.
>>>>>
>>>>> Best,
>>>>> Zhijiang
>>>>>
>>>>>
>>>>> ------------------------------------------------------------------
>>>>> From:Jingsong Li <ji...@gmail.com>
>>>>> Send Time:2020 Feb. 15 (Sat.) 23:21
>>>>> To:dev <de...@flink.apache.org>
>>>>> Subject:Re: [ANNOUNCE] New Documentation Style Guide
>>>>>
>>>>> Thank for the great work,
>>>>>
>>>>> In 1.10, I have modified and reviewed some documents. In that
>> process,
>>>>> sometimes there is some confusion, how to write is the standard. How
>> to
>>>>> write is correct to the users.
>>>>> Docs style now tells me. Learned a lot.
>>>>>
>>>>> Best,
>>>>> Jingsong Lee
>>>>>
>>>>> On Sat, Feb 15, 2020 at 10:00 PM Dian Fu <di...@gmail.com>
>>> wrote:
>>>>>
>>>>>> Thanks for the great work! This is very helpful to keep the
>>>> documentation
>>>>>> style consistent across the whole project. It's also very helpful
>> for
>>>>>> non-native English contributors like me.
>>>>>>
>>>>>>> 在 2020年2月15日，下午3:42，Jark Wu <im...@gmail.com> 写道：
>>>>>>>
>>>>>>> Great summary! Thanks for adding the translation specification in
>>> it.
>>>>>>> I learned a lot from the guide.
>>>>>>>
>>>>>>> Best,
>>>>>>> Jark
>>>>>>>
>>>>>>> On Fri, 14 Feb 2020 at 23:39, Aljoscha Krettek <
>>> aljoscha@apache.org>
>>>>>> wrote:
>>>>>>>
>>>>>>>> Hi Everyone,
>>>>>>>>
>>>>>>>> we just merged a new style guide for documentation writing:
>>>>>>>> https://flink.apache.org/contributing/docs-style.html.
>>>>>>>>
>>>>>>>> Anyone who is writing documentation or is planning to do so
>> should
>>>>> check
>>>>>>>> this out. Please open a Jira Issue or respond here if you have
>> any
>>>>>>>> comments or questions.
>>>>>>>>
>>>>>>>> Some of the most important points in the style guide are:
>>>>>>>>
>>>>>>>> - We should use direct language and address the reader as you
>>>> instead
>>>>>>>> of passive constructions. Please read the guide if you want to
>>>>>>>> understand what this means.
>>>>>>>>
>>>>>>>> - We should use "alert blocks" instead of simple inline alert
>>> tags.
>>>>>>>> Again, please refer to the guide to see what this means exactly
>> if
>>>>>>>> you're not sure.
>>>>>>>>
>>>>>>>> There's plenty more and some interesting links about
>>>>>>>> technical/documentation writing as well.
>>>>>>>>
>>>>>>>> Best,
>>>>>>>> Aljoscha
>>>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>> --
>>>>> Best, Jingsong Lee
>>>>>
>>>>>
>>>>
>>>
>>
>
Re: [ANNOUNCE] New Documentation Style Guide
Posted by jincheng sun <su...@gmail.com>.
Thanks for this great job Aljoscha!
Best,
Jincheng
Yu Li <ca...@gmail.com> 于2020年2月17日周一 下午6:42写道：
> I think the guide itself is a great example of the new style! Thanks for
> driving this, Aljoscha!
>
> Best Regards,
> Yu
>
>
> On Mon, 17 Feb 2020 at 16:44, Becket Qin <be...@gmail.com> wrote:
>
> > The guideline is very practical! I like it! Thanks for putting it
> together,
> > Aljoscha.
> >
> > Jiangjie (Becket) Qin
> >
> > On Mon, Feb 17, 2020 at 10:04 AM Xintong Song <to...@gmail.com>
> > wrote:
> >
> > > Thanks for the summary!
> > >
> > > I've read through the guidelines and found it very helpful. Many of the
> > > questions I had while working on the 1.10 docs the answer can be found
> in
> > > the guideline. And it also inspires me with questions I have never
> > thought
> > > of, especially the language style part.
> > >
> > > Thank you~
> > >
> > > Xintong Song
> > >
> > >
> > >
> > > On Sun, Feb 16, 2020 at 12:55 AM Zhijiang
> > > <wa...@aliyun.com.invalid> wrote:
> > >
> > > > Thanks for bringing this great and valuable document.
> > > >
> > > > I read through the document and was inspired especially by some
> > sections
> > > > in "Voice and Tone" and "General Guiding Principles".
> > > > I think it is not only helpful for writing Flink documents, but also
> > > > provides guideline/benefit for other writings.
> > > > It also reminded me to extend the Flink glossary if necessary.
> > > >
> > > > Best,
> > > > Zhijiang
> > > >
> > > >
> > > > ------------------------------------------------------------------
> > > > From:Jingsong Li <ji...@gmail.com>
> > > > Send Time:2020 Feb. 15 (Sat.) 23:21
> > > > To:dev <de...@flink.apache.org>
> > > > Subject:Re: [ANNOUNCE] New Documentation Style Guide
> > > >
> > > > Thank for the great work,
> > > >
> > > > In 1.10, I have modified and reviewed some documents. In that
> process,
> > > > sometimes there is some confusion, how to write is the standard. How
> to
> > > > write is correct to the users.
> > > > Docs style now tells me. Learned a lot.
> > > >
> > > > Best,
> > > > Jingsong Lee
> > > >
> > > > On Sat, Feb 15, 2020 at 10:00 PM Dian Fu <di...@gmail.com>
> > wrote:
> > > >
> > > > > Thanks for the great work! This is very helpful to keep the
> > > documentation
> > > > > style consistent across the whole project. It's also very helpful
> for
> > > > > non-native English contributors like me.
> > > > >
> > > > > > 在 2020年2月15日，下午3:42，Jark Wu <im...@gmail.com> 写道：
> > > > > >
> > > > > > Great summary! Thanks for adding the translation specification in
> > it.
> > > > > > I learned a lot from the guide.
> > > > > >
> > > > > > Best,
> > > > > > Jark
> > > > > >
> > > > > > On Fri, 14 Feb 2020 at 23:39, Aljoscha Krettek <
> > aljoscha@apache.org>
> > > > > wrote:
> > > > > >
> > > > > >> Hi Everyone,
> > > > > >>
> > > > > >> we just merged a new style guide for documentation writing:
> > > > > >> https://flink.apache.org/contributing/docs-style.html.
> > > > > >>
> > > > > >> Anyone who is writing documentation or is planning to do so
> should
> > > > check
> > > > > >> this out. Please open a Jira Issue or respond here if you have
> any
> > > > > >> comments or questions.
> > > > > >>
> > > > > >> Some of the most important points in the style guide are:
> > > > > >>
> > > > > >> - We should use direct language and address the reader as you
> > > instead
> > > > > >> of passive constructions. Please read the guide if you want to
> > > > > >> understand what this means.
> > > > > >>
> > > > > >> - We should use "alert blocks" instead of simple inline alert
> > tags.
> > > > > >> Again, please refer to the guide to see what this means exactly
> if
> > > > > >> you're not sure.
> > > > > >>
> > > > > >> There's plenty more and some interesting links about
> > > > > >> technical/documentation writing as well.
> > > > > >>
> > > > > >> Best,
> > > > > >> Aljoscha
> > > > > >>
> > > > >
> > > > >
> > > >
> > > > --
> > > > Best, Jingsong Lee
> > > >
> > > >
> > >
> >
>
Re: [ANNOUNCE] New Documentation Style Guide
Posted by Yu Li <ca...@gmail.com>.
I think the guide itself is a great example of the new style! Thanks for
driving this, Aljoscha!
Best Regards,
Yu
On Mon, 17 Feb 2020 at 16:44, Becket Qin <be...@gmail.com> wrote:
> The guideline is very practical! I like it! Thanks for putting it together,
> Aljoscha.
>
> Jiangjie (Becket) Qin
>
> On Mon, Feb 17, 2020 at 10:04 AM Xintong Song <to...@gmail.com>
> wrote:
>
> > Thanks for the summary!
> >
> > I've read through the guidelines and found it very helpful. Many of the
> > questions I had while working on the 1.10 docs the answer can be found in
> > the guideline. And it also inspires me with questions I have never
> thought
> > of, especially the language style part.
> >
> > Thank you~
> >
> > Xintong Song
> >
> >
> >
> > On Sun, Feb 16, 2020 at 12:55 AM Zhijiang
> > <wa...@aliyun.com.invalid> wrote:
> >
> > > Thanks for bringing this great and valuable document.
> > >
> > > I read through the document and was inspired especially by some
> sections
> > > in "Voice and Tone" and "General Guiding Principles".
> > > I think it is not only helpful for writing Flink documents, but also
> > > provides guideline/benefit for other writings.
> > > It also reminded me to extend the Flink glossary if necessary.
> > >
> > > Best,
> > > Zhijiang
> > >
> > >
> > > ------------------------------------------------------------------
> > > From:Jingsong Li <ji...@gmail.com>
> > > Send Time:2020 Feb. 15 (Sat.) 23:21
> > > To:dev <de...@flink.apache.org>
> > > Subject:Re: [ANNOUNCE] New Documentation Style Guide
> > >
> > > Thank for the great work,
> > >
> > > In 1.10, I have modified and reviewed some documents. In that process,
> > > sometimes there is some confusion, how to write is the standard. How to
> > > write is correct to the users.
> > > Docs style now tells me. Learned a lot.
> > >
> > > Best,
> > > Jingsong Lee
> > >
> > > On Sat, Feb 15, 2020 at 10:00 PM Dian Fu <di...@gmail.com>
> wrote:
> > >
> > > > Thanks for the great work! This is very helpful to keep the
> > documentation
> > > > style consistent across the whole project. It's also very helpful for
> > > > non-native English contributors like me.
> > > >
> > > > > 在 2020年2月15日，下午3:42，Jark Wu <im...@gmail.com> 写道：
> > > > >
> > > > > Great summary! Thanks for adding the translation specification in
> it.
> > > > > I learned a lot from the guide.
> > > > >
> > > > > Best,
> > > > > Jark
> > > > >
> > > > > On Fri, 14 Feb 2020 at 23:39, Aljoscha Krettek <
> aljoscha@apache.org>
> > > > wrote:
> > > > >
> > > > >> Hi Everyone,
> > > > >>
> > > > >> we just merged a new style guide for documentation writing:
> > > > >> https://flink.apache.org/contributing/docs-style.html.
> > > > >>
> > > > >> Anyone who is writing documentation or is planning to do so should
> > > check
> > > > >> this out. Please open a Jira Issue or respond here if you have any
> > > > >> comments or questions.
> > > > >>
> > > > >> Some of the most important points in the style guide are:
> > > > >>
> > > > >> - We should use direct language and address the reader as you
> > instead
> > > > >> of passive constructions. Please read the guide if you want to
> > > > >> understand what this means.
> > > > >>
> > > > >> - We should use "alert blocks" instead of simple inline alert
> tags.
> > > > >> Again, please refer to the guide to see what this means exactly if
> > > > >> you're not sure.
> > > > >>
> > > > >> There's plenty more and some interesting links about
> > > > >> technical/documentation writing as well.
> > > > >>
> > > > >> Best,
> > > > >> Aljoscha
> > > > >>
> > > >
> > > >
> > >
> > > --
> > > Best, Jingsong Lee
> > >
> > >
> >
>
Re: [ANNOUNCE] New Documentation Style Guide
Posted by Becket Qin <be...@gmail.com>.
The guideline is very practical! I like it! Thanks for putting it together,
Aljoscha.
Jiangjie (Becket) Qin
On Mon, Feb 17, 2020 at 10:04 AM Xintong Song <to...@gmail.com> wrote:
> Thanks for the summary!
>
> I've read through the guidelines and found it very helpful. Many of the
> questions I had while working on the 1.10 docs the answer can be found in
> the guideline. And it also inspires me with questions I have never thought
> of, especially the language style part.
>
> Thank you~
>
> Xintong Song
>
>
>
> On Sun, Feb 16, 2020 at 12:55 AM Zhijiang
> <wa...@aliyun.com.invalid> wrote:
>
> > Thanks for bringing this great and valuable document.
> >
> > I read through the document and was inspired especially by some sections
> > in "Voice and Tone" and "General Guiding Principles".
> > I think it is not only helpful for writing Flink documents, but also
> > provides guideline/benefit for other writings.
> > It also reminded me to extend the Flink glossary if necessary.
> >
> > Best,
> > Zhijiang
> >
> >
> > ------------------------------------------------------------------
> > From:Jingsong Li <ji...@gmail.com>
> > Send Time:2020 Feb. 15 (Sat.) 23:21
> > To:dev <de...@flink.apache.org>
> > Subject:Re: [ANNOUNCE] New Documentation Style Guide
> >
> > Thank for the great work,
> >
> > In 1.10, I have modified and reviewed some documents. In that process,
> > sometimes there is some confusion, how to write is the standard. How to
> > write is correct to the users.
> > Docs style now tells me. Learned a lot.
> >
> > Best,
> > Jingsong Lee
> >
> > On Sat, Feb 15, 2020 at 10:00 PM Dian Fu <di...@gmail.com> wrote:
> >
> > > Thanks for the great work! This is very helpful to keep the
> documentation
> > > style consistent across the whole project. It's also very helpful for
> > > non-native English contributors like me.
> > >
> > > > 在 2020年2月15日，下午3:42，Jark Wu <im...@gmail.com> 写道：
> > > >
> > > > Great summary! Thanks for adding the translation specification in it.
> > > > I learned a lot from the guide.
> > > >
> > > > Best,
> > > > Jark
> > > >
> > > > On Fri, 14 Feb 2020 at 23:39, Aljoscha Krettek <al...@apache.org>
> > > wrote:
> > > >
> > > >> Hi Everyone,
> > > >>
> > > >> we just merged a new style guide for documentation writing:
> > > >> https://flink.apache.org/contributing/docs-style.html.
> > > >>
> > > >> Anyone who is writing documentation or is planning to do so should
> > check
> > > >> this out. Please open a Jira Issue or respond here if you have any
> > > >> comments or questions.
> > > >>
> > > >> Some of the most important points in the style guide are:
> > > >>
> > > >> - We should use direct language and address the reader as you
> instead
> > > >> of passive constructions. Please read the guide if you want to
> > > >> understand what this means.
> > > >>
> > > >> - We should use "alert blocks" instead of simple inline alert tags.
> > > >> Again, please refer to the guide to see what this means exactly if
> > > >> you're not sure.
> > > >>
> > > >> There's plenty more and some interesting links about
> > > >> technical/documentation writing as well.
> > > >>
> > > >> Best,
> > > >> Aljoscha
> > > >>
> > >
> > >
> >
> > --
> > Best, Jingsong Lee
> >
> >
>
Re: [ANNOUNCE] New Documentation Style Guide
Posted by Xintong Song <to...@gmail.com>.
Thanks for the summary!
I've read through the guidelines and found it very helpful. Many of the
questions I had while working on the 1.10 docs the answer can be found in
the guideline. And it also inspires me with questions I have never thought
of, especially the language style part.
Thank you~
Xintong Song
On Sun, Feb 16, 2020 at 12:55 AM Zhijiang
<wa...@aliyun.com.invalid> wrote:
> Thanks for bringing this great and valuable document.
>
> I read through the document and was inspired especially by some sections
> in "Voice and Tone" and "General Guiding Principles".
> I think it is not only helpful for writing Flink documents, but also
> provides guideline/benefit for other writings.
> It also reminded me to extend the Flink glossary if necessary.
>
> Best,
> Zhijiang
>
>
> ------------------------------------------------------------------
> From:Jingsong Li <ji...@gmail.com>
> Send Time:2020 Feb. 15 (Sat.) 23:21
> To:dev <de...@flink.apache.org>
> Subject:Re: [ANNOUNCE] New Documentation Style Guide
>
> Thank for the great work,
>
> In 1.10, I have modified and reviewed some documents. In that process,
> sometimes there is some confusion, how to write is the standard. How to
> write is correct to the users.
> Docs style now tells me. Learned a lot.
>
> Best,
> Jingsong Lee
>
> On Sat, Feb 15, 2020 at 10:00 PM Dian Fu <di...@gmail.com> wrote:
>
> > Thanks for the great work! This is very helpful to keep the documentation
> > style consistent across the whole project. It's also very helpful for
> > non-native English contributors like me.
> >
> > > 在 2020年2月15日，下午3:42，Jark Wu <im...@gmail.com> 写道：
> > >
> > > Great summary! Thanks for adding the translation specification in it.
> > > I learned a lot from the guide.
> > >
> > > Best,
> > > Jark
> > >
> > > On Fri, 14 Feb 2020 at 23:39, Aljoscha Krettek <al...@apache.org>
> > wrote:
> > >
> > >> Hi Everyone,
> > >>
> > >> we just merged a new style guide for documentation writing:
> > >> https://flink.apache.org/contributing/docs-style.html.
> > >>
> > >> Anyone who is writing documentation or is planning to do so should
> check
> > >> this out. Please open a Jira Issue or respond here if you have any
> > >> comments or questions.
> > >>
> > >> Some of the most important points in the style guide are:
> > >>
> > >> - We should use direct language and address the reader as you instead
> > >> of passive constructions. Please read the guide if you want to
> > >> understand what this means.
> > >>
> > >> - We should use "alert blocks" instead of simple inline alert tags.
> > >> Again, please refer to the guide to see what this means exactly if
> > >> you're not sure.
> > >>
> > >> There's plenty more and some interesting links about
> > >> technical/documentation writing as well.
> > >>
> > >> Best,
> > >> Aljoscha
> > >>
> >
> >
>
> --
> Best, Jingsong Lee
>
>
Re: [ANNOUNCE] New Documentation Style Guide
Posted by Zhijiang <wa...@aliyun.com.INVALID>.
Thanks for bringing this great and valuable document.
I read through the document and was inspired especially by some sections in "Voice and Tone" and "General Guiding Principles".
I think it is not only helpful for writing Flink documents, but also provides guideline/benefit for other writings.
It also reminded me to extend the Flink glossary if necessary.
Best,
Zhijiang
------------------------------------------------------------------
From:Jingsong Li <ji...@gmail.com>
Send Time:2020 Feb. 15 (Sat.) 23:21
To:dev <de...@flink.apache.org>
Subject:Re: [ANNOUNCE] New Documentation Style Guide
Thank for the great work,
In 1.10, I have modified and reviewed some documents. In that process,
sometimes there is some confusion, how to write is the standard. How to
write is correct to the users.
Docs style now tells me. Learned a lot.
Best,
Jingsong Lee
On Sat, Feb 15, 2020 at 10:00 PM Dian Fu <di...@gmail.com> wrote:
> Thanks for the great work! This is very helpful to keep the documentation
> style consistent across the whole project. It's also very helpful for
> non-native English contributors like me.
>
> > 在 2020年2月15日，下午3:42，Jark Wu <im...@gmail.com> 写道：
> >
> > Great summary! Thanks for adding the translation specification in it.
> > I learned a lot from the guide.
> >
> > Best,
> > Jark
> >
> > On Fri, 14 Feb 2020 at 23:39, Aljoscha Krettek <al...@apache.org>
> wrote:
> >
> >> Hi Everyone,
> >>
> >> we just merged a new style guide for documentation writing:
> >> https://flink.apache.org/contributing/docs-style.html.
> >>
> >> Anyone who is writing documentation or is planning to do so should check
> >> this out. Please open a Jira Issue or respond here if you have any
> >> comments or questions.
> >>
> >> Some of the most important points in the style guide are:
> >>
> >> - We should use direct language and address the reader as you instead
> >> of passive constructions. Please read the guide if you want to
> >> understand what this means.
> >>
> >> - We should use "alert blocks" instead of simple inline alert tags.
> >> Again, please refer to the guide to see what this means exactly if
> >> you're not sure.
> >>
> >> There's plenty more and some interesting links about
> >> technical/documentation writing as well.
> >>
> >> Best,
> >> Aljoscha
> >>
>
>
--
Best, Jingsong Lee
Re: [ANNOUNCE] New Documentation Style Guide
Posted by Jingsong Li <ji...@gmail.com>.
Thank for the great work,
In 1.10, I have modified and reviewed some documents. In that process,
sometimes there is some confusion, how to write is the standard. How to
write is correct to the users.
Docs style now tells me. Learned a lot.
Best,
Jingsong Lee
On Sat, Feb 15, 2020 at 10:00 PM Dian Fu <di...@gmail.com> wrote:
> Thanks for the great work! This is very helpful to keep the documentation
> style consistent across the whole project. It's also very helpful for
> non-native English contributors like me.
>
> > 在 2020年2月15日，下午3:42，Jark Wu <im...@gmail.com> 写道：
> >
> > Great summary! Thanks for adding the translation specification in it.
> > I learned a lot from the guide.
> >
> > Best,
> > Jark
> >
> > On Fri, 14 Feb 2020 at 23:39, Aljoscha Krettek <al...@apache.org>
> wrote:
> >
> >> Hi Everyone,
> >>
> >> we just merged a new style guide for documentation writing:
> >> https://flink.apache.org/contributing/docs-style.html.
> >>
> >> Anyone who is writing documentation or is planning to do so should check
> >> this out. Please open a Jira Issue or respond here if you have any
> >> comments or questions.
> >>
> >> Some of the most important points in the style guide are:
> >>
> >> - We should use direct language and address the reader as you instead
> >> of passive constructions. Please read the guide if you want to
> >> understand what this means.
> >>
> >> - We should use "alert blocks" instead of simple inline alert tags.
> >> Again, please refer to the guide to see what this means exactly if
> >> you're not sure.
> >>
> >> There's plenty more and some interesting links about
> >> technical/documentation writing as well.
> >>
> >> Best,
> >> Aljoscha
> >>
>
>
--
Best, Jingsong Lee
Re: [ANNOUNCE] New Documentation Style Guide
Posted by Dian Fu <di...@gmail.com>.
Thanks for the great work! This is very helpful to keep the documentation style consistent across the whole project. It's also very helpful for non-native English contributors like me.
> 在 2020年2月15日，下午3:42，Jark Wu <im...@gmail.com> 写道：
>
> Great summary! Thanks for adding the translation specification in it.
> I learned a lot from the guide.
>
> Best,
> Jark
>
> On Fri, 14 Feb 2020 at 23:39, Aljoscha Krettek <al...@apache.org> wrote:
>
>> Hi Everyone,
>>
>> we just merged a new style guide for documentation writing:
>> https://flink.apache.org/contributing/docs-style.html.
>>
>> Anyone who is writing documentation or is planning to do so should check
>> this out. Please open a Jira Issue or respond here if you have any
>> comments or questions.
>>
>> Some of the most important points in the style guide are:
>>
>> - We should use direct language and address the reader as you instead
>> of passive constructions. Please read the guide if you want to
>> understand what this means.
>>
>> - We should use "alert blocks" instead of simple inline alert tags.
>> Again, please refer to the guide to see what this means exactly if
>> you're not sure.
>>
>> There's plenty more and some interesting links about
>> technical/documentation writing as well.
>>
>> Best,
>> Aljoscha
>>
Re: [ANNOUNCE] New Documentation Style Guide
Posted by Jark Wu <im...@gmail.com>.
Great summary! Thanks for adding the translation specification in it.
I learned a lot from the guide.
Best,
Jark
On Fri, 14 Feb 2020 at 23:39, Aljoscha Krettek <al...@apache.org> wrote:
> Hi Everyone,
>
> we just merged a new style guide for documentation writing:
> https://flink.apache.org/contributing/docs-style.html.
>
> Anyone who is writing documentation or is planning to do so should check
> this out. Please open a Jira Issue or respond here if you have any
> comments or questions.
>
> Some of the most important points in the style guide are:
>
> - We should use direct language and address the reader as you instead
> of passive constructions. Please read the guide if you want to
> understand what this means.
>
> - We should use "alert blocks" instead of simple inline alert tags.
> Again, please refer to the guide to see what this means exactly if
> you're not sure.
>
> There's plenty more and some interesting links about
> technical/documentation writing as well.
>
> Best,
> Aljoscha
>