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 <wangzhijiang...@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 <jingsongl...@gmail.com> > Send Time:2020 Feb. 15 (Sat.) 23:21 > To:dev <dev@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 <dian0511...@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 <imj...@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 <aljos...@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 > >
