(DEPRECATED) Apache Flink Mailing List archive.

[ANNOUNCE] New Documentation Style Guide

Classic

List

Threaded

11 messages Options

Aljoscha Krettek-2

[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

Jark Wu-2

Re: [ANNOUNCE] New Documentation Style Guide

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 <[hidden email]> 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
>

Dian Fu-2

Re: [ANNOUNCE] New Documentation Style Guide

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 <[hidden email]> 写道：
>
> 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 <[hidden email]> 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
>>

Jingsong Li

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 <[hidden email]> 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 <[hidden email]> 写道：
> >
> > 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 <[hidden email]>
> 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

Zhijiang(wangzhijiang999)

Re: [ANNOUNCE] New Documentation Style Guide

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 <[hidden email]>
Send Time:2020 Feb. 15 (Sat.) 23:21
To:dev <[hidden email]>
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 <[hidden email]> wrote:

--
Best, Jingsong Lee

Xintong Song

Re: [ANNOUNCE] New Documentation Style Guide

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
<[hidden email]> 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 <[hidden email]>
> Send Time:2020 Feb. 15 (Sat.) 23:21
> To:dev <[hidden email]>
> 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 <[hidden email]> 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 <[hidden email]> 写道：
> > >
> > > 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 <[hidden email]>
> > 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
>
>

Becket Qin

Re: [ANNOUNCE] New Documentation Style Guide

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 <[hidden email]> 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
> <[hidden email]> 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 <[hidden email]>
> > Send Time:2020 Feb. 15 (Sat.) 23:21
> > To:dev <[hidden email]>
> > 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 <[hidden email]> 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 <[hidden email]> 写道：
> > > >
> > > > 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 <[hidden email]>
> > > 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
> >
> >
>

Yu Li

Re: [ANNOUNCE] New Documentation Style Guide

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 <[hidden email]> 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 <[hidden email]>
> 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
> > <[hidden email]> 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 <[hidden email]>
> > > Send Time:2020 Feb. 15 (Sat.) 23:21
> > > To:dev <[hidden email]>
> > > 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 <[hidden email]>
> 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 <[hidden email]> 写道：
> > > > >
> > > > > 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 <
> [hidden email]>
> > > > 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
> > >
> > >
> >
>

jincheng sun

Re: [ANNOUNCE] New Documentation Style Guide

Thanks for this great job Aljoscha!

Best,
Jincheng

Yu Li <[hidden email]> 于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 <[hidden email]> 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 <[hidden email]>
> > 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
> > > <[hidden email]> 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 <[hidden email]>
> > > > Send Time:2020 Feb. 15 (Sat.) 23:21
> > > > To:dev <[hidden email]>
> > > > 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 <[hidden email]>
> > 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 <[hidden email]> 写道：
> > > > > >
> > > > > > 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 <
> > [hidden email]>
> > > > > 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
> > > >
> > > >
> > >
> >
>

Aljoscha Krettek-2

Re: [ANNOUNCE] New Documentation Style Guide

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 <[hidden email]> 于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 <[hidden email]> 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 <[hidden email]>
>>> 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
>>>> <[hidden email]> 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 <[hidden email]>
>>>>> Send Time:2020 Feb. 15 (Sat.) 23:21
>>>>> To:dev <[hidden email]>
>>>>> 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 <[hidden email]>
>>> 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 <[hidden email]> 写道：
>>>>>>>
>>>>>>> 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 <
>>> [hidden email]>
>>>>>> 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
>>>>>
>>>>>
>>>>
>>>
>>
>

Hequn Cheng-2

Re: [ANNOUNCE] New Documentation Style Guide

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 <[hidden email]>
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 <[hidden email]> 于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 <[hidden email]> 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 <[hidden email]>
> >>> 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
> >>>> <[hidden email]> 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 <[hidden email]>
> >>>>> Send Time:2020 Feb. 15 (Sat.) 23:21
> >>>>> To:dev <[hidden email]>
> >>>>> 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 <[hidden email]>
> >>> 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 <[hidden email]> 写道：
> >>>>>>>
> >>>>>>> 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 <
> >>> [hidden email]>
> >>>>>> 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
> >>>>>
> >>>>>
> >>>>
> >>>
> >>
> >
>