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
Locked
