osdir.com


[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [DISCUSS] Improve Tutorials section of documentation


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 <fhueske@xxxxxxxxx>:

> 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 <trohrmann@xxxxxxxxxx>:
>
>> +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 <yanghua1127@xxxxxxxxx> 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.
>> >
>> > 陈梓立 <wander4096@xxxxxxxxx> 于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 <aljoscha@xxxxxxxxxx> 于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 <fhueske@xxxxxxxxx>
>> 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
>> > > >
>> > > >
>> > >
>> >
>>
>
>