[DISCUSS] Flink Docs Style Guide Review

[Seth Wiesman <sj...@gmail.com>]

Hi All!

A while back, Marta opened a PR to create a documentation style guide as
part of FLIP-42[1][2]. Unfortunately, the review stalled out as everyone
involved got busy with Flink Forward Europe. Since we are approaching the
final stretch for Flink 1.10 and I expect to see an influx in documentation
PR's over the next few weeks I think now is a good time to revive this
guide.

It is important to remember that this is *not* a silver bullet, as language
is fluid and the Flink community is made up of an incredibly diverse and
international group. There are exceptions to virtually every rule in
English and our first goal should always be to write clear and useful
documentation.

That said, this guide can help provide guardrails and structure when needed
while writing and reviewing documentation. It looks to codify the best
practices of what we are already doing as a community and not make any
radical changes. Please take a look at the PR and comment if you have any
concerns. Ideally, we can get this in quickly so it may be referenced while
reviewing 1.10 docs.

Seth

[1]
https://cwiki.apache.org/confluence/display/FLINK/FLIP-42%3A+Rework+Flink+Documentation
[2] https://github.com/apache/flink-web/pull/240

Re: [DISCUSS] Flink Docs Style Guide Review

[Robert Metzger <rm...@apache.org>]

Thanks a lot Seth!

I propose to merge this PR if there's no more feedback within the next 24
hours.

On Mon, Dec 9, 2019 at 6:41 PM Seth Wiesman <sj...@gmail.com> wrote:

> Hi All!
>
> A while back, Marta opened a PR to create a documentation style guide as
> part of FLIP-42[1][2]. Unfortunately, the review stalled out as everyone
> involved got busy with Flink Forward Europe. Since we are approaching the
> final stretch for Flink 1.10 and I expect to see an influx in documentation
> PR's over the next few weeks I think now is a good time to revive this
> guide.
>
> It is important to remember that this is *not* a silver bullet, as language
> is fluid and the Flink community is made up of an incredibly diverse and
> international group. There are exceptions to virtually every rule in
> English and our first goal should always be to write clear and useful
> documentation.
>
> That said, this guide can help provide guardrails and structure when needed
> while writing and reviewing documentation. It looks to codify the best
> practices of what we are already doing as a community and not make any
> radical changes. Please take a look at the PR and comment if you have any
> concerns. Ideally, we can get this in quickly so it may be referenced while
> reviewing 1.10 docs.
>
> Seth
>
> [1]
>
> https://cwiki.apache.org/confluence/display/FLINK/FLIP-42%3A+Rework+Flink+Documentation
> [2] https://github.com/apache/flink-web/pull/240
>