You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@flink.apache.org by Fabian Hueske <fh...@gmail.com> on 2018/08/09 12:44:51 UTC
[DISCUSS] Improve Tutorials section of documentation
Hi everyone,
I'd like to discuss a proposal to improve the tutorials / quickstart guides
of Flink's documentation.
I think the current tutorials have a few issues that should be fix in order
to help our (future) users getting started with Flink.
I propose to add a single "Tutorials" section to the documentation where
users find step-by-step guides. The tutorials section help users with
different goals:
* Get a quick idea of the overall system
* Implement a DataStream/DataSet/Table API/SQL job
* Set up Flink on a local machine (or run a Docker container)
For some of these goals, we do not offer tutorials yet. Our existing
tutorials are mixed with instructions for how to setup an environment to
develop Flink itself ("IDE setup", "Building Flink from Source"), and
reference information that is required to implement applications
("Configuring Dependencies, Connectors, Libraries", Project Templates
Java/Scala).
As a first step, I would like to reorganize this content of the
"Quickstart", "Examples", and "Project Setup" sections of the documentation
depending on the goals of the users (getting started, reference lookup,
developing Flink). So, this would be mostly moving content around.
In a second step, I would improve existing tutorials (Implementing
DataStream applications, Local Setup) and add missing tutorials (Local
Docker setup, Implementing DataSet / Table API / SQL applications, etc.).
What do you think?
Cheers, Fabian
Re: [DISCUSS] Improve Tutorials section of documentation
Posted by Fabian Hueske <fh...@gmail.com>.
Hi everyone,
I've created PR #6565 [1] with the proposed changes.
The PR restructures the docs a bit and mostly moves pages around.
Only deprecated content is removed.
Please let me know what you think.
Thanks,
Fabian
[1] https://github.com/apache/flink/pull/6565
2018-08-10 14:23 GMT+02:00 Fabian Hueske <fh...@gmail.com>:
> Hi,
>
> Thanks for the feedback.
> I've had a look at the structure that was derived from my initial message
> and adjusted it to my current plans (see below).
>
> The main ideas are:
> * add a new Tutorials section and move all existing tutorials there and
> also add new ones.
> * move the "Quickstart" section to "Tutorials".
> * remove the "Project Setup" section and move the pages to other sections
> (some pages will be split up or adjusted).
> * I'm undecided about the "Examples" section but might remove it as well.
>
> Cheers, Fabian
>
> ----
>
> > HOME
>
> - Concepts
> - ...
>
> - Tutorials
> * Quick Tour
> * Developing Flink applications
> - DataStream API (Monitoring the Wikipedia Edit)
> * DataSet API
> * Table API / SQL
> * Setting Up Flink Locally
> - Stand-alone setup (Quickstart + Flink on Windows)
> * Flink with Docker
>
> [- *Examples*
> - Overview
> - Batch Examples
> ]
>
> - Application Development
> - Project Template for Java
> - Project Template for Scala
> - Configuring Dependencies, Connectors, Libraries
> - ...
>
> - Deployment & Operations
> - Building Flink from Source
> - Scala REPL
> - Running Flink on Windows
> - ...
>
> - Debugging & Monitoring
> - ...
>
> - Developing Flink
> - IDE Setup
> - Building Flink from Source
>
> - Internals
> - ...
>
> 2018-08-10 10:49 GMT+02:00 Till Rohrmann <tr...@apache.org>:
>
>> +1
>>
>> I like the idea to disentangle some of our documentation and to tailor it
>> more towards different target groups.
>>
>> Cheers,
>> Till
>>
>> On Fri, Aug 10, 2018 at 5:49 AM vino yang <ya...@gmail.com> wrote:
>>
>> > +1
>> >
>> > I have previously fixed the outdated API usage of the sample code in the
>> > documentation.
>> > In addition, the user also encountered a problem in the mailing list but
>> > the program could not be compiled or the correct result could not be
>> > obtained.
>> > We should come up with a solution to deal with the changes to the API
>> and
>> > the consistency of the sample program.
>> >
>> > Thanks, vino.
>> >
>> > 陈梓立 <wa...@gmail.com> 于2018年8月10日周五 上午10:28写道：
>> >
>> > > Hi Fabian,
>> > >
>> > > +1 for improve tutorials stuff. It's a nice idea that distinguish
>> users
>> > by
>> > > their goals.
>> > > One thing I suggest is that, we could list out the new content
>> designed,
>> > > which would make the discuss more clear.
>> > >
>> > > FYI, the current struct is: (from where I stand)
>> > >
>> > > ```
>> > > > HOME
>> > >
>> > > - Concepts
>> > > - Programming Model
>> > > - Distributed Runtime
>> > > - *Quickstart*
>> > > - *Examples*
>> > > - Overview
>> > > - Monitoring the Wikipedia Edit
>> > > - Batch Example
>> > >
>> > > - *Project Setup*
>> > > - Project Template for Java
>> > > - Project Template for Scala
>> > > - Configuring Dependencies, Connectors, Libaries
>> > > - IDE Setup
>> > > - Scala REPL
>> > > - Running Flink on Windows
>> > > - Building Flink from Source
>> > > - Application Development
>> > > - ...
>> > > - Depolyment & Operations
>> > > - ...
>> > > - Debugging & Monitoring
>> > > - ...
>> > >
>> > > - Internals
>> > > - ...
>> > > ```
>> > >
>> > > Aljoscha Krettek <al...@apache.org> 于2018年8月9日周四 下午11:29写道：
>> > >
>> > > > +1
>> > > >
>> > > > I think this moves us in the direction how having a more hands-on
>> > > > tutorials section where we don't explain all the details and a
>> > reference
>> > > > section where we provide details but don't necessarily spell out a
>> full
>> > > > step-by-step case.
>> > > >
>> > > > > On 9. Aug 2018, at 14:44, Fabian Hueske <fh...@gmail.com>
>> wrote:
>> > > > >
>> > > > > Hi everyone,
>> > > > >
>> > > > > I'd like to discuss a proposal to improve the tutorials /
>> quickstart
>> > > > guides
>> > > > > of Flink's documentation.
>> > > > > I think the current tutorials have a few issues that should be
>> fix in
>> > > > order
>> > > > > to help our (future) users getting started with Flink.
>> > > > >
>> > > > > I propose to add a single "Tutorials" section to the documentation
>> > > where
>> > > > > users find step-by-step guides. The tutorials section help users
>> with
>> > > > > different goals:
>> > > > >
>> > > > > * Get a quick idea of the overall system
>> > > > > * Implement a DataStream/DataSet/Table API/SQL job
>> > > > > * Set up Flink on a local machine (or run a Docker container)
>> > > > >
>> > > > > For some of these goals, we do not offer tutorials yet. Our
>> existing
>> > > > > tutorials are mixed with instructions for how to setup an
>> environment
>> > > to
>> > > > > develop Flink itself ("IDE setup", "Building Flink from Source"),
>> and
>> > > > > reference information that is required to implement applications
>> > > > > ("Configuring Dependencies, Connectors, Libraries", Project
>> Templates
>> > > > > Java/Scala).
>> > > > >
>> > > > > As a first step, I would like to reorganize this content of the
>> > > > > "Quickstart", "Examples", and "Project Setup" sections of the
>> > > > documentation
>> > > > > depending on the goals of the users (getting started, reference
>> > lookup,
>> > > > > developing Flink). So, this would be mostly moving content around.
>> > > > >
>> > > > > In a second step, I would improve existing tutorials (Implementing
>> > > > > DataStream applications, Local Setup) and add missing tutorials
>> > (Local
>> > > > > Docker setup, Implementing DataSet / Table API / SQL applications,
>> > > etc.).
>> > > > >
>> > > > > What do you think?
>> > > > >
>> > > > > Cheers, Fabian
>> > > >
>> > > >
>> > >
>> >
>>
>
>
Re: [DISCUSS] Improve Tutorials section of documentation
Posted by Fabian Hueske <fh...@gmail.com>.
Hi,
Thanks for the feedback.
I've had a look at the structure that was derived from my initial message
and adjusted it to my current plans (see below).
The main ideas are:
* add a new Tutorials section and move all existing tutorials there and
also add new ones.
* move the "Quickstart" section to "Tutorials".
* remove the "Project Setup" section and move the pages to other sections
(some pages will be split up or adjusted).
* I'm undecided about the "Examples" section but might remove it as well.
Cheers, Fabian
----
> HOME
- Concepts
- ...
- Tutorials
* Quick Tour
* Developing Flink applications
- DataStream API (Monitoring the Wikipedia Edit)
* DataSet API
* Table API / SQL
* Setting Up Flink Locally
- Stand-alone setup (Quickstart + Flink on Windows)
* Flink with Docker
[- *Examples*
- Overview
- Batch Examples
]
- Application Development
- Project Template for Java
- Project Template for Scala
- Configuring Dependencies, Connectors, Libraries
- ...
- Deployment & Operations
- Building Flink from Source
- Scala REPL
- Running Flink on Windows
- ...
- Debugging & Monitoring
- ...
- Developing Flink
- IDE Setup
- Building Flink from Source
- Internals
- ...
2018-08-10 10:49 GMT+02:00 Till Rohrmann <tr...@apache.org>:
> +1
>
> I like the idea to disentangle some of our documentation and to tailor it
> more towards different target groups.
>
> Cheers,
> Till
>
> On Fri, Aug 10, 2018 at 5:49 AM vino yang <ya...@gmail.com> wrote:
>
> > +1
> >
> > I have previously fixed the outdated API usage of the sample code in the
> > documentation.
> > In addition, the user also encountered a problem in the mailing list but
> > the program could not be compiled or the correct result could not be
> > obtained.
> > We should come up with a solution to deal with the changes to the API and
> > the consistency of the sample program.
> >
> > Thanks, vino.
> >
> > 陈梓立 <wa...@gmail.com> 于2018年8月10日周五 上午10:28写道：
> >
> > > Hi Fabian,
> > >
> > > +1 for improve tutorials stuff. It's a nice idea that distinguish users
> > by
> > > their goals.
> > > One thing I suggest is that, we could list out the new content
> designed,
> > > which would make the discuss more clear.
> > >
> > > FYI, the current struct is: (from where I stand)
> > >
> > > ```
> > > > HOME
> > >
> > > - Concepts
> > > - Programming Model
> > > - Distributed Runtime
> > > - *Quickstart*
> > > - *Examples*
> > > - Overview
> > > - Monitoring the Wikipedia Edit
> > > - Batch Example
> > >
> > > - *Project Setup*
> > > - Project Template for Java
> > > - Project Template for Scala
> > > - Configuring Dependencies, Connectors, Libaries
> > > - IDE Setup
> > > - Scala REPL
> > > - Running Flink on Windows
> > > - Building Flink from Source
> > > - Application Development
> > > - ...
> > > - Depolyment & Operations
> > > - ...
> > > - Debugging & Monitoring
> > > - ...
> > >
> > > - Internals
> > > - ...
> > > ```
> > >
> > > Aljoscha Krettek <al...@apache.org> 于2018年8月9日周四 下午11:29写道：
> > >
> > > > +1
> > > >
> > > > I think this moves us in the direction how having a more hands-on
> > > > tutorials section where we don't explain all the details and a
> > reference
> > > > section where we provide details but don't necessarily spell out a
> full
> > > > step-by-step case.
> > > >
> > > > > On 9. Aug 2018, at 14:44, Fabian Hueske <fh...@gmail.com> wrote:
> > > > >
> > > > > Hi everyone,
> > > > >
> > > > > I'd like to discuss a proposal to improve the tutorials /
> quickstart
> > > > guides
> > > > > of Flink's documentation.
> > > > > I think the current tutorials have a few issues that should be fix
> in
> > > > order
> > > > > to help our (future) users getting started with Flink.
> > > > >
> > > > > I propose to add a single "Tutorials" section to the documentation
> > > where
> > > > > users find step-by-step guides. The tutorials section help users
> with
> > > > > different goals:
> > > > >
> > > > > * Get a quick idea of the overall system
> > > > > * Implement a DataStream/DataSet/Table API/SQL job
> > > > > * Set up Flink on a local machine (or run a Docker container)
> > > > >
> > > > > For some of these goals, we do not offer tutorials yet. Our
> existing
> > > > > tutorials are mixed with instructions for how to setup an
> environment
> > > to
> > > > > develop Flink itself ("IDE setup", "Building Flink from Source"),
> and
> > > > > reference information that is required to implement applications
> > > > > ("Configuring Dependencies, Connectors, Libraries", Project
> Templates
> > > > > Java/Scala).
> > > > >
> > > > > As a first step, I would like to reorganize this content of the
> > > > > "Quickstart", "Examples", and "Project Setup" sections of the
> > > > documentation
> > > > > depending on the goals of the users (getting started, reference
> > lookup,
> > > > > developing Flink). So, this would be mostly moving content around.
> > > > >
> > > > > In a second step, I would improve existing tutorials (Implementing
> > > > > DataStream applications, Local Setup) and add missing tutorials
> > (Local
> > > > > Docker setup, Implementing DataSet / Table API / SQL applications,
> > > etc.).
> > > > >
> > > > > What do you think?
> > > > >
> > > > > Cheers, Fabian
> > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Improve Tutorials section of documentation
Posted by Till Rohrmann <tr...@apache.org>.
+1
I like the idea to disentangle some of our documentation and to tailor it
more towards different target groups.
Cheers,
Till
On Fri, Aug 10, 2018 at 5:49 AM vino yang <ya...@gmail.com> wrote:
> +1
>
> I have previously fixed the outdated API usage of the sample code in the
> documentation.
> In addition, the user also encountered a problem in the mailing list but
> the program could not be compiled or the correct result could not be
> obtained.
> We should come up with a solution to deal with the changes to the API and
> the consistency of the sample program.
>
> Thanks, vino.
>
> 陈梓立 <wa...@gmail.com> 于2018年8月10日周五 上午10:28写道：
>
> > Hi Fabian,
> >
> > +1 for improve tutorials stuff. It's a nice idea that distinguish users
> by
> > their goals.
> > One thing I suggest is that, we could list out the new content designed,
> > which would make the discuss more clear.
> >
> > FYI, the current struct is: (from where I stand)
> >
> > ```
> > > HOME
> >
> > - Concepts
> > - Programming Model
> > - Distributed Runtime
> > - *Quickstart*
> > - *Examples*
> > - Overview
> > - Monitoring the Wikipedia Edit
> > - Batch Example
> >
> > - *Project Setup*
> > - Project Template for Java
> > - Project Template for Scala
> > - Configuring Dependencies, Connectors, Libaries
> > - IDE Setup
> > - Scala REPL
> > - Running Flink on Windows
> > - Building Flink from Source
> > - Application Development
> > - ...
> > - Depolyment & Operations
> > - ...
> > - Debugging & Monitoring
> > - ...
> >
> > - Internals
> > - ...
> > ```
> >
> > Aljoscha Krettek <al...@apache.org> 于2018年8月9日周四 下午11:29写道：
> >
> > > +1
> > >
> > > I think this moves us in the direction how having a more hands-on
> > > tutorials section where we don't explain all the details and a
> reference
> > > section where we provide details but don't necessarily spell out a full
> > > step-by-step case.
> > >
> > > > On 9. Aug 2018, at 14:44, Fabian Hueske <fh...@gmail.com> wrote:
> > > >
> > > > Hi everyone,
> > > >
> > > > I'd like to discuss a proposal to improve the tutorials / quickstart
> > > guides
> > > > of Flink's documentation.
> > > > I think the current tutorials have a few issues that should be fix in
> > > order
> > > > to help our (future) users getting started with Flink.
> > > >
> > > > I propose to add a single "Tutorials" section to the documentation
> > where
> > > > users find step-by-step guides. The tutorials section help users with
> > > > different goals:
> > > >
> > > > * Get a quick idea of the overall system
> > > > * Implement a DataStream/DataSet/Table API/SQL job
> > > > * Set up Flink on a local machine (or run a Docker container)
> > > >
> > > > For some of these goals, we do not offer tutorials yet. Our existing
> > > > tutorials are mixed with instructions for how to setup an environment
> > to
> > > > develop Flink itself ("IDE setup", "Building Flink from Source"), and
> > > > reference information that is required to implement applications
> > > > ("Configuring Dependencies, Connectors, Libraries", Project Templates
> > > > Java/Scala).
> > > >
> > > > As a first step, I would like to reorganize this content of the
> > > > "Quickstart", "Examples", and "Project Setup" sections of the
> > > documentation
> > > > depending on the goals of the users (getting started, reference
> lookup,
> > > > developing Flink). So, this would be mostly moving content around.
> > > >
> > > > In a second step, I would improve existing tutorials (Implementing
> > > > DataStream applications, Local Setup) and add missing tutorials
> (Local
> > > > Docker setup, Implementing DataSet / Table API / SQL applications,
> > etc.).
> > > >
> > > > What do you think?
> > > >
> > > > Cheers, Fabian
> > >
> > >
> >
>
Re: [DISCUSS] Improve Tutorials section of documentation
Posted by vino yang <ya...@gmail.com>.
+1
I have previously fixed the outdated API usage of the sample code in the
documentation.
In addition, the user also encountered a problem in the mailing list but
the program could not be compiled or the correct result could not be
obtained.
We should come up with a solution to deal with the changes to the API and
the consistency of the sample program.
Thanks, vino.
陈梓立 <wa...@gmail.com> 于2018年8月10日周五 上午10:28写道：
> Hi Fabian,
>
> +1 for improve tutorials stuff. It's a nice idea that distinguish users by
> their goals.
> One thing I suggest is that, we could list out the new content designed,
> which would make the discuss more clear.
>
> FYI, the current struct is: (from where I stand)
>
> ```
> > HOME
>
> - Concepts
> - Programming Model
> - Distributed Runtime
> - *Quickstart*
> - *Examples*
> - Overview
> - Monitoring the Wikipedia Edit
> - Batch Example
>
> - *Project Setup*
> - Project Template for Java
> - Project Template for Scala
> - Configuring Dependencies, Connectors, Libaries
> - IDE Setup
> - Scala REPL
> - Running Flink on Windows
> - Building Flink from Source
> - Application Development
> - ...
> - Depolyment & Operations
> - ...
> - Debugging & Monitoring
> - ...
>
> - Internals
> - ...
> ```
>
> Aljoscha Krettek <al...@apache.org> 于2018年8月9日周四 下午11:29写道：
>
> > +1
> >
> > I think this moves us in the direction how having a more hands-on
> > tutorials section where we don't explain all the details and a reference
> > section where we provide details but don't necessarily spell out a full
> > step-by-step case.
> >
> > > On 9. Aug 2018, at 14:44, Fabian Hueske <fh...@gmail.com> wrote:
> > >
> > > Hi everyone,
> > >
> > > I'd like to discuss a proposal to improve the tutorials / quickstart
> > guides
> > > of Flink's documentation.
> > > I think the current tutorials have a few issues that should be fix in
> > order
> > > to help our (future) users getting started with Flink.
> > >
> > > I propose to add a single "Tutorials" section to the documentation
> where
> > > users find step-by-step guides. The tutorials section help users with
> > > different goals:
> > >
> > > * Get a quick idea of the overall system
> > > * Implement a DataStream/DataSet/Table API/SQL job
> > > * Set up Flink on a local machine (or run a Docker container)
> > >
> > > For some of these goals, we do not offer tutorials yet. Our existing
> > > tutorials are mixed with instructions for how to setup an environment
> to
> > > develop Flink itself ("IDE setup", "Building Flink from Source"), and
> > > reference information that is required to implement applications
> > > ("Configuring Dependencies, Connectors, Libraries", Project Templates
> > > Java/Scala).
> > >
> > > As a first step, I would like to reorganize this content of the
> > > "Quickstart", "Examples", and "Project Setup" sections of the
> > documentation
> > > depending on the goals of the users (getting started, reference lookup,
> > > developing Flink). So, this would be mostly moving content around.
> > >
> > > In a second step, I would improve existing tutorials (Implementing
> > > DataStream applications, Local Setup) and add missing tutorials (Local
> > > Docker setup, Implementing DataSet / Table API / SQL applications,
> etc.).
> > >
> > > What do you think?
> > >
> > > Cheers, Fabian
> >
> >
>
Re: [DISCUSS] Improve Tutorials section of documentation
Posted by 陈梓立 <wa...@gmail.com>.
Hi Fabian,
+1 for improve tutorials stuff. It's a nice idea that distinguish users by
their goals.
One thing I suggest is that, we could list out the new content designed,
which would make the discuss more clear.
FYI, the current struct is: (from where I stand)
```
> HOME
- Concepts
- Programming Model
- Distributed Runtime
- *Quickstart*
- *Examples*
- Overview
- Monitoring the Wikipedia Edit
- Batch Example
- *Project Setup*
- Project Template for Java
- Project Template for Scala
- Configuring Dependencies, Connectors, Libaries
- IDE Setup
- Scala REPL
- Running Flink on Windows
- Building Flink from Source
- Application Development
- ...
- Depolyment & Operations
- ...
- Debugging & Monitoring
- ...
- Internals
- ...
```
Aljoscha Krettek <al...@apache.org> 于2018年8月9日周四 下午11:29写道：
> +1
>
> I think this moves us in the direction how having a more hands-on
> tutorials section where we don't explain all the details and a reference
> section where we provide details but don't necessarily spell out a full
> step-by-step case.
>
> > On 9. Aug 2018, at 14:44, Fabian Hueske <fh...@gmail.com> wrote:
> >
> > Hi everyone,
> >
> > I'd like to discuss a proposal to improve the tutorials / quickstart
> guides
> > of Flink's documentation.
> > I think the current tutorials have a few issues that should be fix in
> order
> > to help our (future) users getting started with Flink.
> >
> > I propose to add a single "Tutorials" section to the documentation where
> > users find step-by-step guides. The tutorials section help users with
> > different goals:
> >
> > * Get a quick idea of the overall system
> > * Implement a DataStream/DataSet/Table API/SQL job
> > * Set up Flink on a local machine (or run a Docker container)
> >
> > For some of these goals, we do not offer tutorials yet. Our existing
> > tutorials are mixed with instructions for how to setup an environment to
> > develop Flink itself ("IDE setup", "Building Flink from Source"), and
> > reference information that is required to implement applications
> > ("Configuring Dependencies, Connectors, Libraries", Project Templates
> > Java/Scala).
> >
> > As a first step, I would like to reorganize this content of the
> > "Quickstart", "Examples", and "Project Setup" sections of the
> documentation
> > depending on the goals of the users (getting started, reference lookup,
> > developing Flink). So, this would be mostly moving content around.
> >
> > In a second step, I would improve existing tutorials (Implementing
> > DataStream applications, Local Setup) and add missing tutorials (Local
> > Docker setup, Implementing DataSet / Table API / SQL applications, etc.).
> >
> > What do you think?
> >
> > Cheers, Fabian
>
>
Re: [DISCUSS] Improve Tutorials section of documentation
Posted by Aljoscha Krettek <al...@apache.org>.
+1
I think this moves us in the direction how having a more hands-on tutorials section where we don't explain all the details and a reference section where we provide details but don't necessarily spell out a full step-by-step case.
> On 9. Aug 2018, at 14:44, Fabian Hueske <fh...@gmail.com> wrote:
>
> Hi everyone,
>
> I'd like to discuss a proposal to improve the tutorials / quickstart guides
> of Flink's documentation.
> I think the current tutorials have a few issues that should be fix in order
> to help our (future) users getting started with Flink.
>
> I propose to add a single "Tutorials" section to the documentation where
> users find step-by-step guides. The tutorials section help users with
> different goals:
>
> * Get a quick idea of the overall system
> * Implement a DataStream/DataSet/Table API/SQL job
> * Set up Flink on a local machine (or run a Docker container)
>
> For some of these goals, we do not offer tutorials yet. Our existing
> tutorials are mixed with instructions for how to setup an environment to
> develop Flink itself ("IDE setup", "Building Flink from Source"), and
> reference information that is required to implement applications
> ("Configuring Dependencies, Connectors, Libraries", Project Templates
> Java/Scala).
>
> As a first step, I would like to reorganize this content of the
> "Quickstart", "Examples", and "Project Setup" sections of the documentation
> depending on the goals of the users (getting started, reference lookup,
> developing Flink). So, this would be mostly moving content around.
>
> In a second step, I would improve existing tutorials (Implementing
> DataStream applications, Local Setup) and add missing tutorials (Local
> Docker setup, Implementing DataSet / Table API / SQL applications, etc.).
>
> What do you think?
>
> Cheers, Fabian