[DISCUSS] FLIP to Restructure, Update & Rework Apache Flink's Documentation

[Konstantin Knauf-3]

Hi all,

following our unsuccessful application to Season of Docs Fabian, Seth,
Stephan and myself have drafted a FLIP for reworking our documentation and
implementing some (or most) of the changes, we would have liked to tackle
in SoD.

The overarching goals of the FLIP are:

* Top-level structure with clear separation of concerns

* Expand and restructure existing Concepts section

* Align Application Development with current state and Flink roadmap

* Improve documentation on Deployment & Operations

** *Improve getting-started experience

* Use of a common terminology

* Add a documentation style guide


It is quite an ambitions endeavor, but we can tackle these changes in
multiple phases and we will benefit from it even if the whole FLIP takes
some time to be implemented.

The whole description of the FLIP (proposed documentation structure &
sections, changes, implementation plan) is available on Google Docs [1] for
now for simplicity. I will move it to Confluence once we have reached
consensus.

Please let us know what you think and I am looking forward to your
feedback, opinions and comments on the proposal.

Cheers,

Konstantin

[1]
https://docs.google.com/document/d/1pPM4vTWUUiJb73pd8OqHA1EWVl9cv6kXoCB5F7_J6gM/edit?usp=sharing


--

Konstantin Knauf | Solutions Architect

[phone]


Planned Absences: 20. - 21.06.2019


<https://www.ververica.com/>

Follow us @VervericaData

--

Join Flink Forward <https://flink-forward.org/> - The Apache Flink
Conference

Stream Processing | Event Driven | Real Time

--

Data Artisans GmbH | Invalidenstrasse 115, 10115 Berlin, Germany

--
Data Artisans GmbH
Registered at Amtsgericht Charlottenburg: HRB 158244 B
Managing Directors: Dr. Kostas Tzoumas, Dr. Stephan Ewen

[Robert Metzger]

Thanks a lot for working on this FLIP!  I just read it, and it seems well
written and well thought out.
+1 from my side to put it into Confluence and start working on the docs :)



On Mon, May 20, 2019 at 7:23 PM Konstantin Knauf <[hidden email]>
wrote:

> Hi all,
>
> following our unsuccessful application to Season of Docs Fabian, Seth,
> Stephan and myself have drafted a FLIP for reworking our documentation and
> implementing some (or most) of the changes, we would have liked to tackle
> in SoD.
>
> The overarching goals of the FLIP are:
>
> * Top-level structure with clear separation of concerns
>
> * Expand and restructure existing Concepts section
>
> * Align Application Development with current state and Flink roadmap
>
> * Improve documentation on Deployment & Operations
>
> ** *Improve getting-started experience
>
> * Use of a common terminology
>
> * Add a documentation style guide
>
>
> It is quite an ambitions endeavor, but we can tackle these changes in
> multiple phases and we will benefit from it even if the whole FLIP takes
> some time to be implemented.
>
> The whole description of the FLIP (proposed documentation structure &
> sections, changes, implementation plan) is available on Google Docs [1] for
> now for simplicity. I will move it to Confluence once we have reached
> consensus.
>
> Please let us know what you think and I am looking forward to your
> feedback, opinions and comments on the proposal.
>
> Cheers,
>
> Konstantin
>
> [1]
>
> https://docs.google.com/document/d/1pPM4vTWUUiJb73pd8OqHA1EWVl9cv6kXoCB5F7_J6gM/edit?usp=sharing
>
>
> --
>
> Konstantin Knauf | Solutions Architect
>
> [phone]
>
>
> Planned Absences: 20. - 21.06.2019
>
>
> <https://www.ververica.com/>
>
> Follow us @VervericaData
>
> --
>
> Join Flink Forward <https://flink-forward.org/> - The Apache Flink
> Conference
>
> Stream Processing | Event Driven | Real Time
>
> --
>
> Data Artisans GmbH | Invalidenstrasse 115, 10115 Berlin, Germany
>
> --
> Data Artisans GmbH
> Registered at Amtsgericht Charlottenburg: HRB 158244 B
> Managing Directors: Dr. Kostas Tzoumas, Dr. Stephan Ewen
>

[Jark Wu-2]

Hi Konstantin,

Thanks a lot for preparing this FLIP. It's great to see we can continue the
work on improving documentation.
I have read it and +1 from my side. And I will coordination Chinese
translation work and this FLIP.

Regards,
Jark



On Wed, 22 May 2019 at 16:02, Robert Metzger <[hidden email]> wrote:

> Thanks a lot for working on this FLIP!  I just read it, and it seems well
> written and well thought out.
> +1 from my side to put it into Confluence and start working on the docs :)
>
>
>
> On Mon, May 20, 2019 at 7:23 PM Konstantin Knauf <[hidden email]
> >
> wrote:
>
> > Hi all,
> >
> > following our unsuccessful application to Season of Docs Fabian, Seth,
> > Stephan and myself have drafted a FLIP for reworking our documentation
> and
> > implementing some (or most) of the changes, we would have liked to tackle
> > in SoD.
> >
> > The overarching goals of the FLIP are:
> >
> > * Top-level structure with clear separation of concerns
> >
> > * Expand and restructure existing Concepts section
> >
> > * Align Application Development with current state and Flink roadmap
> >
> > * Improve documentation on Deployment & Operations
> >
> > ** *Improve getting-started experience
> >
> > * Use of a common terminology
> >
> > * Add a documentation style guide
> >
> >
> > It is quite an ambitions endeavor, but we can tackle these changes in
> > multiple phases and we will benefit from it even if the whole FLIP takes
> > some time to be implemented.
> >
> > The whole description of the FLIP (proposed documentation structure &
> > sections, changes, implementation plan) is available on Google Docs [1]
> for
> > now for simplicity. I will move it to Confluence once we have reached
> > consensus.
> >
> > Please let us know what you think and I am looking forward to your
> > feedback, opinions and comments on the proposal.
> >
> > Cheers,
> >
> > Konstantin
> >
> > [1]
> >
> >
> https://docs.google.com/document/d/1pPM4vTWUUiJb73pd8OqHA1EWVl9cv6kXoCB5F7_J6gM/edit?usp=sharing
> >
> >
> > --
> >
> > Konstantin Knauf | Solutions Architect
> >
> > [phone]
> >
> >
> > Planned Absences: 20. - 21.06.2019
> >
> >
> > <https://www.ververica.com/>
> >
> > Follow us @VervericaData
> >
> > --
> >
> > Join Flink Forward <https://flink-forward.org/> - The Apache Flink
> > Conference
> >
> > Stream Processing | Event Driven | Real Time
> >
> > --
> >
> > Data Artisans GmbH | Invalidenstrasse 115, 10115 Berlin, Germany
> >
> > --
> > Data Artisans GmbH
> > Registered at Amtsgericht Charlottenburg: HRB 158244 B
> > Managing Directors: Dr. Kostas Tzoumas, Dr. Stephan Ewen
> >
>

[Fabian Hueske-2]

Hi All,

I obviously support this proposal, but I'd like to emphasize two points.

* I think we can significantly improve the getting-started experience with
better (and up-to-date) tutorials.
* A better structure and separation of concepts and API will be very
helpful. I noticed this when I was reading/searching the docs to write my
book.

@Jark Thanks for your awesome work on the Chinese translation of the docs
(and website)!

Cheers,
Fabian

Am Do., 23. Mai 2019 um 04:58 Uhr schrieb Jark Wu <[hidden email]>:

> Hi Konstantin,
>
> Thanks a lot for preparing this FLIP. It's great to see we can continue the
> work on improving documentation.
> I have read it and +1 from my side. And I will coordination Chinese
> translation work and this FLIP.
>
> Regards,
> Jark
>
>
>
> On Wed, 22 May 2019 at 16:02, Robert Metzger <[hidden email]> wrote:
>
> > Thanks a lot for working on this FLIP!  I just read it, and it seems well
> > written and well thought out.
> > +1 from my side to put it into Confluence and start working on the docs
> :)
> >
> >
> >
> > On Mon, May 20, 2019 at 7:23 PM Konstantin Knauf <
> [hidden email]
> > >
> > wrote:
> >
> > > Hi all,
> > >
> > > following our unsuccessful application to Season of Docs Fabian, Seth,
> > > Stephan and myself have drafted a FLIP for reworking our documentation
> > and
> > > implementing some (or most) of the changes, we would have liked to
> tackle
> > > in SoD.
> > >
> > > The overarching goals of the FLIP are:
> > >
> > > * Top-level structure with clear separation of concerns
> > >
> > > * Expand and restructure existing Concepts section
> > >
> > > * Align Application Development with current state and Flink roadmap
> > >
> > > * Improve documentation on Deployment & Operations
> > >
> > > ** *Improve getting-started experience
> > >
> > > * Use of a common terminology
> > >
> > > * Add a documentation style guide
> > >
> > >
> > > It is quite an ambitions endeavor, but we can tackle these changes in
> > > multiple phases and we will benefit from it even if the whole FLIP
> takes
> > > some time to be implemented.
> > >
> > > The whole description of the FLIP (proposed documentation structure &
> > > sections, changes, implementation plan) is available on Google Docs [1]
> > for
> > > now for simplicity. I will move it to Confluence once we have reached
> > > consensus.
> > >
> > > Please let us know what you think and I am looking forward to your
> > > feedback, opinions and comments on the proposal.
> > >
> > > Cheers,
> > >
> > > Konstantin
> > >
> > > [1]
> > >
> > >
> >
> https://docs.google.com/document/d/1pPM4vTWUUiJb73pd8OqHA1EWVl9cv6kXoCB5F7_J6gM/edit?usp=sharing
> > >
> > >
> > > --
> > >
> > > Konstantin Knauf | Solutions Architect
> > >
> > > [phone]
> > >
> > >
> > > Planned Absences: 20. - 21.06.2019
> > >
> > >
> > > <https://www.ververica.com/>
> > >
> > > Follow us @VervericaData
> > >
> > > --
> > >
> > > Join Flink Forward <https://flink-forward.org/> - The Apache Flink
> > > Conference
> > >
> > > Stream Processing | Event Driven | Real Time
> > >
> > > --
> > >
> > > Data Artisans GmbH | Invalidenstrasse 115, 10115 Berlin, Germany
> > >
> > > --
> > > Data Artisans GmbH
> > > Registered at Amtsgericht Charlottenburg: HRB 158244 B
> > > Managing Directors: Dr. Kostas Tzoumas, Dr. Stephan Ewen
> > >
> >
>

[Konstantin Knauf-3]

Hi everyone,

thank you all for your comments. I agree with Fabian, there are a lot of
independent contributions subsumed in this FLIP (like Concepts or Getting
Started), which indepdently will already make a big difference for new
users.

It looks like overall, the FLIP is accepted. Therefore, I have moved the
FLIP into Confluence [1] (as FLIP-42) and created a JIRA ticket for it [2].
In the course of the day I will create a couple of sub-task tickets for the
first steps.

In the meantime, please feel free to reach out if you would like to
collaborate on this effort or would like to discuss it further.

Cheers,

Konstantin

[1]
https://cwiki.apache.org/confluence/display/FLINK/FLIP-42%3A+Rework+Flink+Documentation
[2] https://issues.apache.org/jira/browse/FLINK-12639





On Mon, May 27, 2019 at 11:27 AM Fabian Hueske <[hidden email]> wrote:

> Hi All,
>
> I obviously support this proposal, but I'd like to emphasize two points.
>
> * I think we can significantly improve the getting-started experience with
> better (and up-to-date) tutorials.
> * A better structure and separation of concepts and API will be very
> helpful. I noticed this when I was reading/searching the docs to write my
> book.
>
> @Jark Thanks for your awesome work on the Chinese translation of the docs
> (and website)!
>
> Cheers,
> Fabian
>
> Am Do., 23. Mai 2019 um 04:58 Uhr schrieb Jark Wu <[hidden email]>:
>
> > Hi Konstantin,
> >
> > Thanks a lot for preparing this FLIP. It's great to see we can continue
> the
> > work on improving documentation.
> > I have read it and +1 from my side. And I will coordination Chinese
> > translation work and this FLIP.
> >
> > Regards,
> > Jark
> >
> >
> >
> > On Wed, 22 May 2019 at 16:02, Robert Metzger <[hidden email]>
> wrote:
> >
> > > Thanks a lot for working on this FLIP!  I just read it, and it seems
> well
> > > written and well thought out.
> > > +1 from my side to put it into Confluence and start working on the docs
> > :)
> > >
> > >
> > >
> > > On Mon, May 20, 2019 at 7:23 PM Konstantin Knauf <
> > [hidden email]
> > > >
> > > wrote:
> > >
> > > > Hi all,
> > > >
> > > > following our unsuccessful application to Season of Docs Fabian,
> Seth,
> > > > Stephan and myself have drafted a FLIP for reworking our
> documentation
> > > and
> > > > implementing some (or most) of the changes, we would have liked to
> > tackle
> > > > in SoD.
> > > >
> > > > The overarching goals of the FLIP are:
> > > >
> > > > * Top-level structure with clear separation of concerns
> > > >
> > > > * Expand and restructure existing Concepts section
> > > >
> > > > * Align Application Development with current state and Flink roadmap
> > > >
> > > > * Improve documentation on Deployment & Operations
> > > >
> > > > ** *Improve getting-started experience
> > > >
> > > > * Use of a common terminology
> > > >
> > > > * Add a documentation style guide
> > > >
> > > >
> > > > It is quite an ambitions endeavor, but we can tackle these changes in
> > > > multiple phases and we will benefit from it even if the whole FLIP
> > takes
> > > > some time to be implemented.
> > > >
> > > > The whole description of the FLIP (proposed documentation structure &
> > > > sections, changes, implementation plan) is available on Google Docs
> [1]
> > > for
> > > > now for simplicity. I will move it to Confluence once we have reached
> > > > consensus.
> > > >
> > > > Please let us know what you think and I am looking forward to your
> > > > feedback, opinions and comments on the proposal.
> > > >
> > > > Cheers,
> > > >
> > > > Konstantin
> > > >
> > > > [1]
> > > >
> > > >
> > >
> >
> https://docs.google.com/document/d/1pPM4vTWUUiJb73pd8OqHA1EWVl9cv6kXoCB5F7_J6gM/edit?usp=sharing
> > > >
> > > >
> > > > --
> > > >
> > > > Konstantin Knauf | Solutions Architect
> > > >
> > > > [phone]
> > > >
> > > >
> > > > Planned Absences: 20. - 21.06.2019
> > > >
> > > >
> > > > <https://www.ververica.com/>
> > > >
> > > > Follow us @VervericaData
> > > >
> > > > --
> > > >
> > > > Join Flink Forward <https://flink-forward.org/> - The Apache Flink
> > > > Conference
> > > >
> > > > Stream Processing | Event Driven | Real Time
> > > >
> > > > --
> > > >
> > > > Data Artisans GmbH | Invalidenstrasse 115, 10115 Berlin, Germany
> > > >
> > > > --
> > > > Data Artisans GmbH
> > > > Registered at Amtsgericht Charlottenburg: HRB 158244 B
> > > > Managing Directors: Dr. Kostas Tzoumas, Dr. Stephan Ewen
> > > >
> > >
> >
>

--

Konstantin Knauf | Solutions Architect

[phone]


Planned Absences: 20. - 21.06.2019


<https://www.ververica.com/>

Follow us @VervericaData

--

Join Flink Forward <https://flink-forward.org/> - The Apache Flink
Conference

Stream Processing | Event Driven | Real Time

--

Data Artisans GmbH | Invalidenstrasse 115, 10115 Berlin, Germany

--
Data Artisans GmbH
Registered at Amtsgericht Charlottenburg: HRB 158244 B
Managing Directors: Dr. Kostas Tzoumas, Dr. Stephan Ewen