Hi David,
I am happy to get the repo created for you.
If we go with the documentation (vs flink.apache.org) do you think we
should remove any of the existing content? There is already a getting
started section with quickstarts and walkthroughs and a concepts section.
In particular, the concepts section today is not complete and almost every
page on master contains multiple TODOs. I don't believe anyone is working
on these. What do you think about replacing the current concepts section
with the training material? I just re-examined the training site and I
believe it covers the same material as concepts but better. Of course, we
would salvage anything worth keeping, like the glossary.
Seth
On Wed, Apr 15, 2020 at 2:02 PM David Anderson <da...@ververica.com>
wrote:
Thank you all for the very positive response to our proposal to
contribute
the training materials that have been at training.ververica.com to the
Apache Flink project. Now I’d like to begin the more detailed discussion
of
how to go about this.
In that earlier thread I mentioned that we were thinking of merging the
markdown-based web pages into flink.apache.org, and to add the exercises
to
flink-playgrounds. This was based on thinking that it would be something
of
a maintenance headache to add the website content into the docs, where it
would have to be versioned.
Since then, a better approach has been suggested:
We already have quite a bit of “getting started” material in the docs:
Code
Walkthroughs, Docker Playgrounds, Tutorials, and Examples. Having a
second
location (namely flink.apache.org) where this kind of content could be
found doesn’t seem ideal. So let’s go ahead and add the expository
content
from the training materials to the documentation, with pointers into the
rest of the docs (which are already present in the training), and with
pointers to the exercises (rather than including the exercise
descriptions
in the docs). This will keep the content that will need more frequent
revision out of the documentation.
Then let’s create a new repo -- named flink-training -- that contains the
exercises, the solutions, and the tests that go with them, PLUS all of
the
material that describes how to get setup to do the exercises, the
explanations for each exercise, and accompanying discussion material that
should be read after doing each exercise. Note that the exercise
solutions
already have tests, and Travis is already being used for CI on the
existing
project, so CI shouldn’t be an issue.
Action Item: would a committer or PMC member kindly volunteer to help
with
creating this new flink-training repo?
With the content refactored in this way, I believe ongoing maintenance
won’t be much trouble. With each new Flink release I’ve been updating the
exercises to build against the latest release, and to avoid any newly
deprecated parts of the API. But since these exercises are focused on the
most basic parts of the API, that hasn’t been difficult. As for content
from the training website that would move into the docs, this content is
much more stable, and has only needed a gentle revision every year or
two.
Regards,
David
