Web Page Issue

[Matthias J. Sax-2]

Hi,

I am not sure, but I guess there is something wrong on the web page. If
you click on "Overview" in the menu bar at the start page
(https://flink.apache.org/), it links to https://flink.apache.org/index.html

This seems to be wrong to me. I guess it should link to
https://ci.apache.org/projects/flink/flink-docs-release-0.9/index.html
("Overview" links to this page if you first go to "Quickstart -> Setup"
for example)

While this can be easily fixed, the more fundamental problem here seems
to be the "duality" of the web page. We have the flink-web.git
repository and the "doc" folder in flink.git. Thus, it can easily happen
that both parts get out-of-sync.

Both parts are hosted on different URLs, too (https://flink.apache.org
and https://ci.apache.org/projects/flink). I personally think, this is
not too nice, and if I want to change something, it is always confusion
which part of the web page originates from which git repo. Furthermore,
the menu bars of both pages are not 100% identical. (Right now, the menu
bars need to be kept in sync manually.)

Additionally, a few pages have no content. For example:
https://ci.apache.org/projects/flink/flink-docs-release-0.9/internals/how_to_contribute.html

> "The How to Contribute guide is located on the project website."

Why not link to the correct page in the first place?


What is the reason for this duality? It there a good way to avoid (some
automatic checks?) that both parts go out-of-sync? Should be try to
"merge" both parts together? I am just raising "random" questions about
it. I guess there is a good reason for the current situation that I am
not aware of. From my point of view, there are two ways to go. Either,
merge both parts completely, or separate them more strictly (such that
it gets clear that it is actually two web pages and not one).


-Matthias

[Fabian Hueske-2]

The website consists of two parts which are maintained in two separate
respositories:

1) The project website about features, community, etc.
2) The documentation of the project

We have the separation because we want to be able to update source and
documentation in one repository to avoid that the documentation gets out of
sync. The documentation is built every night and hosted at ci.apache.org to
achieve that.

IMO, this separation makes sense, because the project website is not
changed very often whereas the documentation should be touched whenever the
API or behavior is changed. I think it is very important to have
documentation in sync with the code. In fact, I believe both parts of the
website should not be related to each other, so they shouldn't be a way to
have both parts getting out-of-sync, except for layout / design which is
nice to have but not crucial. We might even think about changing the
color-scheme of the documentation to make the difference more clear.

2015-10-26 10:12 GMT+01:00 Matthias J. Sax <[hidden email]>:

> Hi,
>
> I am not sure, but I guess there is something wrong on the web page. If
> you click on "Overview" in the menu bar at the start page
> (https://flink.apache.org/), it links to
> https://flink.apache.org/index.html
>
> This seems to be wrong to me. I guess it should link to
> https://ci.apache.org/projects/flink/flink-docs-release-0.9/index.html
> ("Overview" links to this page if you first go to "Quickstart -> Setup"
> for example)
>
> While this can be easily fixed, the more fundamental problem here seems
> to be the "duality" of the web page. We have the flink-web.git
> repository and the "doc" folder in flink.git. Thus, it can easily happen
> that both parts get out-of-sync.
>
> Both parts are hosted on different URLs, too (https://flink.apache.org
> and https://ci.apache.org/projects/flink). I personally think, this is
> not too nice, and if I want to change something, it is always confusion
> which part of the web page originates from which git repo. Furthermore,
> the menu bars of both pages are not 100% identical. (Right now, the menu
> bars need to be kept in sync manually.)
>
> Additionally, a few pages have no content. For example:
>
> https://ci.apache.org/projects/flink/flink-docs-release-0.9/internals/how_to_contribute.html
>
> > "The How to Contribute guide is located on the project website."
>
> Why not link to the correct page in the first place?
>
>
> What is the reason for this duality? It there a good way to avoid (some
> automatic checks?) that both parts go out-of-sync? Should be try to
> "merge" both parts together? I am just raising "random" questions about
> it. I guess there is a good reason for the current situation that I am
> not aware of. From my point of view, there are two ways to go. Either,
> merge both parts completely, or separate them more strictly (such that
> it gets clear that it is actually two web pages and not one).
>
>
> -Matthias
>
>

[Ufuk Celebi-2]

> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]> wrote:
>
> The website consists of two parts which are maintained in two separate
> respositories:
>
> 1) The project website about features, community, etc.
> 2) The documentation of the project
>
> We have the separation because we want to be able to update source and
> documentation in one repository to avoid that the documentation gets out of
> sync. The documentation is built every night and hosted at ci.apache.org to
> achieve that.
>
> IMO, this separation makes sense, because the project website is not
> changed very often whereas the documentation should be touched whenever the
> API or behavior is changed. I think it is very important to have
> documentation in sync with the code. In fact, I believe both parts of the
> website should not be related to each other, so they shouldn't be a way to
> have both parts getting out-of-sync, except for layout / design which is
> nice to have but not crucial. We might even think about changing the
> color-scheme of the documentation to make the difference more clear.

Yes, Max pointed this out in the beginning. Let’s change the colors/design to make the distinction clear. The confusion comes from the fact that they look similar. It only makes sense to assume that they are hosted on the same web server etc. But as Fabian said, there are good reasons against it.

– Ufuk

[mxm]

Thanks Matthias for pointing this out. I opened an issue some time ago with
a similar description: https://issues.apache.org/jira/browse/FLINK-2752

I agree with Fabian and Ufuk that it makes sense to separate the website
and the source repository. However, the distinction between the
documentation and the homepage should be more clear.

On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]> wrote:

>
> > On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]> wrote:
> >
> > The website consists of two parts which are maintained in two separate
> > respositories:
> >
> > 1) The project website about features, community, etc.
> > 2) The documentation of the project
> >
> > We have the separation because we want to be able to update source and
> > documentation in one repository to avoid that the documentation gets out
> of
> > sync. The documentation is built every night and hosted at ci.apache.org
> to
> > achieve that.
> >
> > IMO, this separation makes sense, because the project website is not
> > changed very often whereas the documentation should be touched whenever
> the
> > API or behavior is changed. I think it is very important to have
> > documentation in sync with the code. In fact, I believe both parts of the
> > website should not be related to each other, so they shouldn't be a way
> to
> > have both parts getting out-of-sync, except for layout / design which is
> > nice to have but not crucial. We might even think about changing the
> > color-scheme of the documentation to make the difference more clear.
>
> Yes, Max pointed this out in the beginning. Let’s change the colors/design
> to make the distinction clear. The confusion comes from the fact that they
> look similar. It only makes sense to assume that they are hosted on the
> same web server etc. But as Fabian said, there are good reasons against it.
>
> – Ufuk

[Matthias J. Sax-2]

Makes sense.

Besides the color scheme, we might also want to use different menu
structure and avoid to link "forth-and-back" to make the distinction
clearer.

On 10/26/2015 10:35 AM, Ufuk Celebi wrote:

>
>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]> wrote:
>>
>> The website consists of two parts which are maintained in two separate
>> respositories:
>>
>> 1) The project website about features, community, etc.
>> 2) The documentation of the project
>>
>> We have the separation because we want to be able to update source and
>> documentation in one repository to avoid that the documentation gets out of
>> sync. The documentation is built every night and hosted at ci.apache.org to
>> achieve that.
>>
>> IMO, this separation makes sense, because the project website is not
>> changed very often whereas the documentation should be touched whenever the
>> API or behavior is changed. I think it is very important to have
>> documentation in sync with the code. In fact, I believe both parts of the
>> website should not be related to each other, so they shouldn't be a way to
>> have both parts getting out-of-sync, except for layout / design which is
>> nice to have but not crucial. We might even think about changing the
>> color-scheme of the documentation to make the difference more clear.
>
> Yes, Max pointed this out in the beginning. Let’s change the colors/design to make the distinction clear. The confusion comes from the fact that they look similar. It only makes sense to assume that they are hosted on the same web server etc. But as Fabian said, there are good reasons against it.
>
> – Ufuk
>

[Matthias J. Sax-2]

I started to work on this. Please see here:
https://github.com/mjsax/flink/tree/flink-2752-webpage

Basically, I just changed the color schema of the menu. I also remove
"How to Contribute" and "Coding Guidelines" from "Internals".

To get an even better separation, I would like to change the menu from
the main web page, too.

 - At least we should change the link of "Overview" which is not useful
at all, right now (is it broken or intentionally?)
 - I would also move "Quickstart" as sub-menu point of "Documentation"
 - maybe we could move "Overview" as sub-menu point of "Documentation", too

From my point of view, having a different menu structure and color
should be good enough to make the distinction of both pages clear.

Btw: the link "setup guide" in *Getting Started* section at the main
page is broken... I would fix this together with those changes (if
accepted).

Please give feedback.

-Matthias

On 10/26/2015 10:40 AM, Maximilian Michels wrote:

> Thanks Matthias for pointing this out. I opened an issue some time ago with
> a similar description: https://issues.apache.org/jira/browse/FLINK-2752
>
> I agree with Fabian and Ufuk that it makes sense to separate the website
> and the source repository. However, the distinction between the
> documentation and the homepage should be more clear.
>
> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]> wrote:
>
>>
>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]> wrote:
>>>
>>> The website consists of two parts which are maintained in two separate
>>> respositories:
>>>
>>> 1) The project website about features, community, etc.
>>> 2) The documentation of the project
>>>
>>> We have the separation because we want to be able to update source and
>>> documentation in one repository to avoid that the documentation gets out
>> of
>>> sync. The documentation is built every night and hosted at ci.apache.org
>> to
>>> achieve that.
>>>
>>> IMO, this separation makes sense, because the project website is not
>>> changed very often whereas the documentation should be touched whenever
>> the
>>> API or behavior is changed. I think it is very important to have
>>> documentation in sync with the code. In fact, I believe both parts of the
>>> website should not be related to each other, so they shouldn't be a way
>> to
>>> have both parts getting out-of-sync, except for layout / design which is
>>> nice to have but not crucial. We might even think about changing the
>>> color-scheme of the documentation to make the difference more clear.
>>
>> Yes, Max pointed this out in the beginning. Let’s change the colors/design
>> to make the distinction clear. The confusion comes from the fact that they
>> look similar. It only makes sense to assume that they are hosted on the
>> same web server etc. But as Fabian said, there are good reasons against it.
>>
>> – Ufuk
>

[Fabian Hueske-2]

Hi Matthias,

thanks for taking care of this issue.
How about we change the menu completely, i.e., have menue entries for:

- Project Website
- Setup
  - Local
  - Cluster
  - Yarn
- DataSet API
  - Programming guide
  - transformations
- DataStream API
  - Programming Guide
- Internals

This is not a complete list, just what came to my mind right now.

Cheers,
Fabian

2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:

> I started to work on this. Please see here:
> https://github.com/mjsax/flink/tree/flink-2752-webpage
>
> Basically, I just changed the color schema of the menu. I also remove
> "How to Contribute" and "Coding Guidelines" from "Internals".
>
> To get an even better separation, I would like to change the menu from
> the main web page, too.
>
>  - At least we should change the link of "Overview" which is not useful
> at all, right now (is it broken or intentionally?)
>  - I would also move "Quickstart" as sub-menu point of "Documentation"
>  - maybe we could move "Overview" as sub-menu point of "Documentation", too
>
> From my point of view, having a different menu structure and color
> should be good enough to make the distinction of both pages clear.
>
> Btw: the link "setup guide" in *Getting Started* section at the main
> page is broken... I would fix this together with those changes (if
> accepted).
>
> Please give feedback.
>
> -Matthias
>
> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
> > Thanks Matthias for pointing this out. I opened an issue some time ago
> with
> > a similar description: https://issues.apache.org/jira/browse/FLINK-2752
> >
> > I agree with Fabian and Ufuk that it makes sense to separate the website
> > and the source repository. However, the distinction between the
> > documentation and the homepage should be more clear.
> >
> > On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]> wrote:
> >
> >>
> >>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]> wrote:
> >>>
> >>> The website consists of two parts which are maintained in two separate
> >>> respositories:
> >>>
> >>> 1) The project website about features, community, etc.
> >>> 2) The documentation of the project
> >>>
> >>> We have the separation because we want to be able to update source and
> >>> documentation in one repository to avoid that the documentation gets
> out
> >> of
> >>> sync. The documentation is built every night and hosted at
> ci.apache.org
> >> to
> >>> achieve that.
> >>>
> >>> IMO, this separation makes sense, because the project website is not
> >>> changed very often whereas the documentation should be touched whenever
> >> the
> >>> API or behavior is changed. I think it is very important to have
> >>> documentation in sync with the code. In fact, I believe both parts of
> the
> >>> website should not be related to each other, so they shouldn't be a way
> >> to
> >>> have both parts getting out-of-sync, except for layout / design which
> is
> >>> nice to have but not crucial. We might even think about changing the
> >>> color-scheme of the documentation to make the difference more clear.
> >>
> >> Yes, Max pointed this out in the beginning. Let’s change the
> colors/design
> >> to make the distinction clear. The confusion comes from the fact that
> they
> >> look similar. It only makes sense to assume that they are hosted on the
> >> same web server etc. But as Fabian said, there are good reasons against
> it.
> >>
> >> – Ufuk
> >
>
>

[Matthias J. Sax-2]

Thanks for the input Fabian!

I was actually referring to the main page regarding changes of the menu
structure.

Currently, the layout is:

>    FlinkLogo    |  Overview   | Quickstart  | Features | Download | Documentation | FAQ || Blog | Community | Project
> (-> index.html)  (-> doc page) (-> doc page)                        (-> doc page)

I would change it to

>    FlinkLogo    | Features | Download | Documentation | FAQ || Blog | Community | Project
> (-> index.html)                         (-> doc page)

With Documentation:
  - Overview
  - Quickstart (Setup)
  - Latest Release (Doc, JavaDoc, ScalaDoc)
  - Snapshot (Doc, JavaDoc, ScalaDoc)
  - Wiki

This give the advantage, that only a single menu points to the doc page.

In the doc page, I would keep the Flink logo that points back to the
main web page.

> FlinkLogo | Overview | Quickstart | Setup | Programming Guides | Libraries | Internals

We could split "Programming Guides" into "DataSet API" and "DataStream
API". The question is about all the other menu point of "Programming
Guides".

Where to move "Best Practice", "Examples", "Local Execution", "Cluster
Execution", "Command Line Interface", "Web Client", and "Java 8" ??

=> "Python", "Interactive Scale Shell", "Connectors", "Iterations",
"Hadoop" could go to "DataSet API"
=> "Storm" could go to "DataStream API"
=> as an alternative, "Pyhton", "Hadoop", and "Storm" could go to
"Libraries" too


-Matthias



On 10/27/2015 11:42 AM, Fabian Hueske wrote:

> Hi Matthias,
>
> thanks for taking care of this issue.
> How about we change the menu completely, i.e., have menue entries for:
>
> - Project Website
> - Setup
>   - Local
>   - Cluster
>   - Yarn
> - DataSet API
>   - Programming guide
>   - transformations
> - DataStream API
>   - Programming Guide
> - Internals
>
> This is not a complete list, just what came to my mind right now.
>
> Cheers,
> Fabian
>
> 2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>
>> I started to work on this. Please see here:
>> https://github.com/mjsax/flink/tree/flink-2752-webpage
>>
>> Basically, I just changed the color schema of the menu. I also remove
>> "How to Contribute" and "Coding Guidelines" from "Internals".
>>
>> To get an even better separation, I would like to change the menu from
>> the main web page, too.
>>
>>  - At least we should change the link of "Overview" which is not useful
>> at all, right now (is it broken or intentionally?)
>>  - I would also move "Quickstart" as sub-menu point of "Documentation"
>>  - maybe we could move "Overview" as sub-menu point of "Documentation", too
>>
>> From my point of view, having a different menu structure and color
>> should be good enough to make the distinction of both pages clear.
>>
>> Btw: the link "setup guide" in *Getting Started* section at the main
>> page is broken... I would fix this together with those changes (if
>> accepted).
>>
>> Please give feedback.
>>
>> -Matthias
>>
>> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
>>> Thanks Matthias for pointing this out. I opened an issue some time ago
>> with
>>> a similar description: https://issues.apache.org/jira/browse/FLINK-2752
>>>
>>> I agree with Fabian and Ufuk that it makes sense to separate the website
>>> and the source repository. However, the distinction between the
>>> documentation and the homepage should be more clear.
>>>
>>> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]> wrote:
>>>
>>>>
>>>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]> wrote:
>>>>>
>>>>> The website consists of two parts which are maintained in two separate
>>>>> respositories:
>>>>>
>>>>> 1) The project website about features, community, etc.
>>>>> 2) The documentation of the project
>>>>>
>>>>> We have the separation because we want to be able to update source and
>>>>> documentation in one repository to avoid that the documentation gets
>> out
>>>> of
>>>>> sync. The documentation is built every night and hosted at
>> ci.apache.org
>>>> to
>>>>> achieve that.
>>>>>
>>>>> IMO, this separation makes sense, because the project website is not
>>>>> changed very often whereas the documentation should be touched whenever
>>>> the
>>>>> API or behavior is changed. I think it is very important to have
>>>>> documentation in sync with the code. In fact, I believe both parts of
>> the
>>>>> website should not be related to each other, so they shouldn't be a way
>>>> to
>>>>> have both parts getting out-of-sync, except for layout / design which
>> is
>>>>> nice to have but not crucial. We might even think about changing the
>>>>> color-scheme of the documentation to make the difference more clear.
>>>>
>>>> Yes, Max pointed this out in the beginning. Let’s change the
>> colors/design
>>>> to make the distinction clear. The confusion comes from the fact that
>> they
>>>> look similar. It only makes sense to assume that they are hosted on the
>>>> same web server etc. But as Fabian said, there are good reasons against
>> it.
>>>>
>>>> – Ufuk
>>>
>>
>>
>

[Fabian Hueske-2]

I agree that it is confusing that the documentation is linked more than
once from the project website menu. It is not clear when you enter the
documentation section and how to get back.

However, the "Overview" menu entry on the project website does not point to
the documentation but to http://flink.apache.org/index.html. Hence, it can
stay in the menu and should not be moved under Documentation.

I would also add a dedicated "Project Website" link to the Documentation
menu in addition to the link on the logo.

2015-10-27 20:39 GMT+01:00 Matthias J. Sax <[hidden email]>:

> Thanks for the input Fabian!
>
> I was actually referring to the main page regarding changes of the menu
> structure.
>
> Currently, the layout is:
>
> >    FlinkLogo    |  Overview   | Quickstart  | Features | Download |
> Documentation | FAQ || Blog | Community | Project
> > (-> index.html)  (-> doc page) (-> doc page)                        (->
> doc page)
>
> I would change it to
>
> >    FlinkLogo    | Features | Download | Documentation | FAQ || Blog |
> Community | Project
> > (-> index.html)                         (-> doc page)
>
> With Documentation:
>   - Overview
>   - Quickstart (Setup)
>   - Latest Release (Doc, JavaDoc, ScalaDoc)
>   - Snapshot (Doc, JavaDoc, ScalaDoc)
>   - Wiki
>
> This give the advantage, that only a single menu points to the doc page.
>
> In the doc page, I would keep the Flink logo that points back to the
> main web page.
>
> > FlinkLogo | Overview | Quickstart | Setup | Programming Guides |
> Libraries | Internals
>
> We could split "Programming Guides" into "DataSet API" and "DataStream
> API". The question is about all the other menu point of "Programming
> Guides".
>
> Where to move "Best Practice", "Examples", "Local Execution", "Cluster
> Execution", "Command Line Interface", "Web Client", and "Java 8" ??
>
> => "Python", "Interactive Scale Shell", "Connectors", "Iterations",
> "Hadoop" could go to "DataSet API"
> => "Storm" could go to "DataStream API"
> => as an alternative, "Pyhton", "Hadoop", and "Storm" could go to
> "Libraries" too
>
>
> -Matthias
>
>
>
> On 10/27/2015 11:42 AM, Fabian Hueske wrote:
> > Hi Matthias,
> >
> > thanks for taking care of this issue.
> > How about we change the menu completely, i.e., have menue entries for:
> >
> > - Project Website
> > - Setup
> >   - Local
> >   - Cluster
> >   - Yarn
> > - DataSet API
> >   - Programming guide
> >   - transformations
> > - DataStream API
> >   - Programming Guide
> > - Internals
> >
> > This is not a complete list, just what came to my mind right now.
> >
> > Cheers,
> > Fabian
> >
> > 2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
> >
> >> I started to work on this. Please see here:
> >> https://github.com/mjsax/flink/tree/flink-2752-webpage
> >>
> >> Basically, I just changed the color schema of the menu. I also remove
> >> "How to Contribute" and "Coding Guidelines" from "Internals".
> >>
> >> To get an even better separation, I would like to change the menu from
> >> the main web page, too.
> >>
> >>  - At least we should change the link of "Overview" which is not useful
> >> at all, right now (is it broken or intentionally?)
> >>  - I would also move "Quickstart" as sub-menu point of "Documentation"
> >>  - maybe we could move "Overview" as sub-menu point of "Documentation",
> too
> >>
> >> From my point of view, having a different menu structure and color
> >> should be good enough to make the distinction of both pages clear.
> >>
> >> Btw: the link "setup guide" in *Getting Started* section at the main
> >> page is broken... I would fix this together with those changes (if
> >> accepted).
> >>
> >> Please give feedback.
> >>
> >> -Matthias
> >>
> >> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
> >>> Thanks Matthias for pointing this out. I opened an issue some time ago
> >> with
> >>> a similar description:
> https://issues.apache.org/jira/browse/FLINK-2752
> >>>
> >>> I agree with Fabian and Ufuk that it makes sense to separate the
> website
> >>> and the source repository. However, the distinction between the
> >>> documentation and the homepage should be more clear.
> >>>
> >>> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]> wrote:
> >>>
> >>>>
> >>>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]> wrote:
> >>>>>
> >>>>> The website consists of two parts which are maintained in two
> separate
> >>>>> respositories:
> >>>>>
> >>>>> 1) The project website about features, community, etc.
> >>>>> 2) The documentation of the project
> >>>>>
> >>>>> We have the separation because we want to be able to update source
> and
> >>>>> documentation in one repository to avoid that the documentation gets
> >> out
> >>>> of
> >>>>> sync. The documentation is built every night and hosted at
> >> ci.apache.org
> >>>> to
> >>>>> achieve that.
> >>>>>
> >>>>> IMO, this separation makes sense, because the project website is not
> >>>>> changed very often whereas the documentation should be touched
> whenever
> >>>> the
> >>>>> API or behavior is changed. I think it is very important to have
> >>>>> documentation in sync with the code. In fact, I believe both parts of
> >> the
> >>>>> website should not be related to each other, so they shouldn't be a
> way
> >>>> to
> >>>>> have both parts getting out-of-sync, except for layout / design which
> >> is
> >>>>> nice to have but not crucial. We might even think about changing the
> >>>>> color-scheme of the documentation to make the difference more clear.
> >>>>
> >>>> Yes, Max pointed this out in the beginning. Let’s change the
> >> colors/design
> >>>> to make the distinction clear. The confusion comes from the fact that
> >> they
> >>>> look similar. It only makes sense to assume that they are hosted on
> the
> >>>> same web server etc. But as Fabian said, there are good reasons
> against
> >> it.
> >>>>
> >>>> – Ufuk
> >>>
> >>
> >>
> >
>
>

[Matthias J. Sax-2]

Yes, but I think that the "Overview" link to index.html is
confusing/wrong. The doc web page has "Overview" too, and it points to
https://ci.apache.org/projects/flink/flink-docs-master/index.html

There should be only one page with name "Overview" (either on the web
page or on the doc page). I actually thought, that the "Overview" link
from the main page should point to the documentation overview and is
currently just wrong?

Last but not least, using the Logo and an additional "Overview" menu
point both pointing to the same location is redundant. I would just go
with the logo as a link (or if an explicit menu point is used, disable
the logo as a link -- too me, it is always confusing it two links next
to each other do the same thing).

-Matthias



On 10/27/2015 11:56 PM, Fabian Hueske wrote:

> I agree that it is confusing that the documentation is linked more than
> once from the project website menu. It is not clear when you enter the
> documentation section and how to get back.
>
> However, the "Overview" menu entry on the project website does not point to
> the documentation but to http://flink.apache.org/index.html. Hence, it can
> stay in the menu and should not be moved under Documentation.
>
> I would also add a dedicated "Project Website" link to the Documentation
> menu in addition to the link on the logo.
>
> 2015-10-27 20:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>
>> Thanks for the input Fabian!
>>
>> I was actually referring to the main page regarding changes of the menu
>> structure.
>>
>> Currently, the layout is:
>>
>>>    FlinkLogo    |  Overview   | Quickstart  | Features | Download |
>> Documentation | FAQ || Blog | Community | Project
>>> (-> index.html)  (-> doc page) (-> doc page)                        (->
>> doc page)
>>
>> I would change it to
>>
>>>    FlinkLogo    | Features | Download | Documentation | FAQ || Blog |
>> Community | Project
>>> (-> index.html)                         (-> doc page)
>>
>> With Documentation:
>>   - Overview
>>   - Quickstart (Setup)
>>   - Latest Release (Doc, JavaDoc, ScalaDoc)
>>   - Snapshot (Doc, JavaDoc, ScalaDoc)
>>   - Wiki
>>
>> This give the advantage, that only a single menu points to the doc page.
>>
>> In the doc page, I would keep the Flink logo that points back to the
>> main web page.
>>
>>> FlinkLogo | Overview | Quickstart | Setup | Programming Guides |
>> Libraries | Internals
>>
>> We could split "Programming Guides" into "DataSet API" and "DataStream
>> API". The question is about all the other menu point of "Programming
>> Guides".
>>
>> Where to move "Best Practice", "Examples", "Local Execution", "Cluster
>> Execution", "Command Line Interface", "Web Client", and "Java 8" ??
>>
>> => "Python", "Interactive Scale Shell", "Connectors", "Iterations",
>> "Hadoop" could go to "DataSet API"
>> => "Storm" could go to "DataStream API"
>> => as an alternative, "Pyhton", "Hadoop", and "Storm" could go to
>> "Libraries" too
>>
>>
>> -Matthias
>>
>>
>>
>> On 10/27/2015 11:42 AM, Fabian Hueske wrote:
>>> Hi Matthias,
>>>
>>> thanks for taking care of this issue.
>>> How about we change the menu completely, i.e., have menue entries for:
>>>
>>> - Project Website
>>> - Setup
>>>   - Local
>>>   - Cluster
>>>   - Yarn
>>> - DataSet API
>>>   - Programming guide
>>>   - transformations
>>> - DataStream API
>>>   - Programming Guide
>>> - Internals
>>>
>>> This is not a complete list, just what came to my mind right now.
>>>
>>> Cheers,
>>> Fabian
>>>
>>> 2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>
>>>> I started to work on this. Please see here:
>>>> https://github.com/mjsax/flink/tree/flink-2752-webpage
>>>>
>>>> Basically, I just changed the color schema of the menu. I also remove
>>>> "How to Contribute" and "Coding Guidelines" from "Internals".
>>>>
>>>> To get an even better separation, I would like to change the menu from
>>>> the main web page, too.
>>>>
>>>>  - At least we should change the link of "Overview" which is not useful
>>>> at all, right now (is it broken or intentionally?)
>>>>  - I would also move "Quickstart" as sub-menu point of "Documentation"
>>>>  - maybe we could move "Overview" as sub-menu point of "Documentation",
>> too
>>>>
>>>> From my point of view, having a different menu structure and color
>>>> should be good enough to make the distinction of both pages clear.
>>>>
>>>> Btw: the link "setup guide" in *Getting Started* section at the main
>>>> page is broken... I would fix this together with those changes (if
>>>> accepted).
>>>>
>>>> Please give feedback.
>>>>
>>>> -Matthias
>>>>
>>>> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
>>>>> Thanks Matthias for pointing this out. I opened an issue some time ago
>>>> with
>>>>> a similar description:
>> https://issues.apache.org/jira/browse/FLINK-2752
>>>>>
>>>>> I agree with Fabian and Ufuk that it makes sense to separate the
>> website
>>>>> and the source repository. However, the distinction between the
>>>>> documentation and the homepage should be more clear.
>>>>>
>>>>> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]> wrote:
>>>>>
>>>>>>
>>>>>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]> wrote:
>>>>>>>
>>>>>>> The website consists of two parts which are maintained in two
>> separate
>>>>>>> respositories:
>>>>>>>
>>>>>>> 1) The project website about features, community, etc.
>>>>>>> 2) The documentation of the project
>>>>>>>
>>>>>>> We have the separation because we want to be able to update source
>> and
>>>>>>> documentation in one repository to avoid that the documentation gets
>>>> out
>>>>>> of
>>>>>>> sync. The documentation is built every night and hosted at
>>>> ci.apache.org
>>>>>> to
>>>>>>> achieve that.
>>>>>>>
>>>>>>> IMO, this separation makes sense, because the project website is not
>>>>>>> changed very often whereas the documentation should be touched
>> whenever
>>>>>> the
>>>>>>> API or behavior is changed. I think it is very important to have
>>>>>>> documentation in sync with the code. In fact, I believe both parts of
>>>> the
>>>>>>> website should not be related to each other, so they shouldn't be a
>> way
>>>>>> to
>>>>>>> have both parts getting out-of-sync, except for layout / design which
>>>> is
>>>>>>> nice to have but not crucial. We might even think about changing the
>>>>>>> color-scheme of the documentation to make the difference more clear.
>>>>>>
>>>>>> Yes, Max pointed this out in the beginning. Let’s change the
>>>> colors/design
>>>>>> to make the distinction clear. The confusion comes from the fact that
>>>> they
>>>>>> look similar. It only makes sense to assume that they are hosted on
>> the
>>>>>> same web server etc. But as Fabian said, there are good reasons
>> against
>>>> it.
>>>>>>
>>>>>> – Ufuk
>>>>>
>>>>
>>>>
>>>
>>
>>
>

[Fabian Hueske-2]

I agree, two Overview links pointing to different locations should be
changed.
I am not so sure about the Logo issue. IMO, there should be always a text
link. The logo link should only be an addition.

Maybe we should wait for more opinions, before we continue.
The website has been changed a couple of times, so it would be good to get
input from those who built the current website, IMO.


2015-10-28 9:56 GMT+01:00 Matthias J. Sax <[hidden email]>:

> Yes, but I think that the "Overview" link to index.html is
> confusing/wrong. The doc web page has "Overview" too, and it points to
> https://ci.apache.org/projects/flink/flink-docs-master/index.html
>
> There should be only one page with name "Overview" (either on the web
> page or on the doc page). I actually thought, that the "Overview" link
> from the main page should point to the documentation overview and is
> currently just wrong?
>
> Last but not least, using the Logo and an additional "Overview" menu
> point both pointing to the same location is redundant. I would just go
> with the logo as a link (or if an explicit menu point is used, disable
> the logo as a link -- too me, it is always confusing it two links next
> to each other do the same thing).
>
> -Matthias
>
>
>
> On 10/27/2015 11:56 PM, Fabian Hueske wrote:
> > I agree that it is confusing that the documentation is linked more than
> > once from the project website menu. It is not clear when you enter the
> > documentation section and how to get back.
> >
> > However, the "Overview" menu entry on the project website does not point
> to
> > the documentation but to http://flink.apache.org/index.html. Hence, it
> can
> > stay in the menu and should not be moved under Documentation.
> >
> > I would also add a dedicated "Project Website" link to the Documentation
> > menu in addition to the link on the logo.
> >
> > 2015-10-27 20:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
> >
> >> Thanks for the input Fabian!
> >>
> >> I was actually referring to the main page regarding changes of the menu
> >> structure.
> >>
> >> Currently, the layout is:
> >>
> >>>    FlinkLogo    |  Overview   | Quickstart  | Features | Download |
> >> Documentation | FAQ || Blog | Community | Project
> >>> (-> index.html)  (-> doc page) (-> doc page)                        (->
> >> doc page)
> >>
> >> I would change it to
> >>
> >>>    FlinkLogo    | Features | Download | Documentation | FAQ || Blog |
> >> Community | Project
> >>> (-> index.html)                         (-> doc page)
> >>
> >> With Documentation:
> >>   - Overview
> >>   - Quickstart (Setup)
> >>   - Latest Release (Doc, JavaDoc, ScalaDoc)
> >>   - Snapshot (Doc, JavaDoc, ScalaDoc)
> >>   - Wiki
> >>
> >> This give the advantage, that only a single menu points to the doc page.
> >>
> >> In the doc page, I would keep the Flink logo that points back to the
> >> main web page.
> >>
> >>> FlinkLogo | Overview | Quickstart | Setup | Programming Guides |
> >> Libraries | Internals
> >>
> >> We could split "Programming Guides" into "DataSet API" and "DataStream
> >> API". The question is about all the other menu point of "Programming
> >> Guides".
> >>
> >> Where to move "Best Practice", "Examples", "Local Execution", "Cluster
> >> Execution", "Command Line Interface", "Web Client", and "Java 8" ??
> >>
> >> => "Python", "Interactive Scale Shell", "Connectors", "Iterations",
> >> "Hadoop" could go to "DataSet API"
> >> => "Storm" could go to "DataStream API"
> >> => as an alternative, "Pyhton", "Hadoop", and "Storm" could go to
> >> "Libraries" too
> >>
> >>
> >> -Matthias
> >>
> >>
> >>
> >> On 10/27/2015 11:42 AM, Fabian Hueske wrote:
> >>> Hi Matthias,
> >>>
> >>> thanks for taking care of this issue.
> >>> How about we change the menu completely, i.e., have menue entries for:
> >>>
> >>> - Project Website
> >>> - Setup
> >>>   - Local
> >>>   - Cluster
> >>>   - Yarn
> >>> - DataSet API
> >>>   - Programming guide
> >>>   - transformations
> >>> - DataStream API
> >>>   - Programming Guide
> >>> - Internals
> >>>
> >>> This is not a complete list, just what came to my mind right now.
> >>>
> >>> Cheers,
> >>> Fabian
> >>>
> >>> 2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
> >>>
> >>>> I started to work on this. Please see here:
> >>>> https://github.com/mjsax/flink/tree/flink-2752-webpage
> >>>>
> >>>> Basically, I just changed the color schema of the menu. I also remove
> >>>> "How to Contribute" and "Coding Guidelines" from "Internals".
> >>>>
> >>>> To get an even better separation, I would like to change the menu from
> >>>> the main web page, too.
> >>>>
> >>>>  - At least we should change the link of "Overview" which is not
> useful
> >>>> at all, right now (is it broken or intentionally?)
> >>>>  - I would also move "Quickstart" as sub-menu point of "Documentation"
> >>>>  - maybe we could move "Overview" as sub-menu point of
> "Documentation",
> >> too
> >>>>
> >>>> From my point of view, having a different menu structure and color
> >>>> should be good enough to make the distinction of both pages clear.
> >>>>
> >>>> Btw: the link "setup guide" in *Getting Started* section at the main
> >>>> page is broken... I would fix this together with those changes (if
> >>>> accepted).
> >>>>
> >>>> Please give feedback.
> >>>>
> >>>> -Matthias
> >>>>
> >>>> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
> >>>>> Thanks Matthias for pointing this out. I opened an issue some time
> ago
> >>>> with
> >>>>> a similar description:
> >> https://issues.apache.org/jira/browse/FLINK-2752
> >>>>>
> >>>>> I agree with Fabian and Ufuk that it makes sense to separate the
> >> website
> >>>>> and the source repository. However, the distinction between the
> >>>>> documentation and the homepage should be more clear.
> >>>>>
> >>>>> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]>
> wrote:
> >>>>>
> >>>>>>
> >>>>>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]> wrote:
> >>>>>>>
> >>>>>>> The website consists of two parts which are maintained in two
> >> separate
> >>>>>>> respositories:
> >>>>>>>
> >>>>>>> 1) The project website about features, community, etc.
> >>>>>>> 2) The documentation of the project
> >>>>>>>
> >>>>>>> We have the separation because we want to be able to update source
> >> and
> >>>>>>> documentation in one repository to avoid that the documentation
> gets
> >>>> out
> >>>>>> of
> >>>>>>> sync. The documentation is built every night and hosted at
> >>>> ci.apache.org
> >>>>>> to
> >>>>>>> achieve that.
> >>>>>>>
> >>>>>>> IMO, this separation makes sense, because the project website is
> not
> >>>>>>> changed very often whereas the documentation should be touched
> >> whenever
> >>>>>> the
> >>>>>>> API or behavior is changed. I think it is very important to have
> >>>>>>> documentation in sync with the code. In fact, I believe both parts
> of
> >>>> the
> >>>>>>> website should not be related to each other, so they shouldn't be a
> >> way
> >>>>>> to
> >>>>>>> have both parts getting out-of-sync, except for layout / design
> which
> >>>> is
> >>>>>>> nice to have but not crucial. We might even think about changing
> the
> >>>>>>> color-scheme of the documentation to make the difference more
> clear.
> >>>>>>
> >>>>>> Yes, Max pointed this out in the beginning. Let’s change the
> >>>> colors/design
> >>>>>> to make the distinction clear. The confusion comes from the fact
> that
> >>>> they
> >>>>>> look similar. It only makes sense to assume that they are hosted on
> >> the
> >>>>>> same web server etc. But as Fabian said, there are good reasons
> >> against
> >>>> it.
> >>>>>>
> >>>>>> – Ufuk
> >>>>>
> >>>>
> >>>>
> >>>
> >>
> >>
> >
>
>

[mxm]

We should be careful not to break links to the docs again. I'm in
favor of making it more clear what is the Flink web site and what its
documentation is. For me, it would be enough to change "Overview 1.0"
to "Documentation 1.0" and have a clear link which says "Back to Flink
website". That should do it.

In the light of the release, all other changes are not that important
to me right now but I wouldn't deny the structure of the documentation
can be improved.

On Wed, Oct 28, 2015 at 10:05 AM, Fabian Hueske <[hidden email]> wrote:

>
> I agree, two Overview links pointing to different locations should be
> changed.
> I am not so sure about the Logo issue. IMO, there should be always a text
> link. The logo link should only be an addition.
>
> Maybe we should wait for more opinions, before we continue.
> The website has been changed a couple of times, so it would be good to get
> input from those who built the current website, IMO.
>
>
> 2015-10-28 9:56 GMT+01:00 Matthias J. Sax <[hidden email]>:
>
> > Yes, but I think that the "Overview" link to index.html is
> > confusing/wrong. The doc web page has "Overview" too, and it points to
> > https://ci.apache.org/projects/flink/flink-docs-master/index.html
> >
> > There should be only one page with name "Overview" (either on the web
> > page or on the doc page). I actually thought, that the "Overview" link
> > from the main page should point to the documentation overview and is
> > currently just wrong?
> >
> > Last but not least, using the Logo and an additional "Overview" menu
> > point both pointing to the same location is redundant. I would just go
> > with the logo as a link (or if an explicit menu point is used, disable
> > the logo as a link -- too me, it is always confusing it two links next
> > to each other do the same thing).
> >
> > -Matthias
> >
> >
> >
> > On 10/27/2015 11:56 PM, Fabian Hueske wrote:
> > > I agree that it is confusing that the documentation is linked more than
> > > once from the project website menu. It is not clear when you enter the
> > > documentation section and how to get back.
> > >
> > > However, the "Overview" menu entry on the project website does not point
> > to
> > > the documentation but to http://flink.apache.org/index.html. Hence, it
> > can
> > > stay in the menu and should not be moved under Documentation.
> > >
> > > I would also add a dedicated "Project Website" link to the Documentation
> > > menu in addition to the link on the logo.
> > >
> > > 2015-10-27 20:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
> > >
> > >> Thanks for the input Fabian!
> > >>
> > >> I was actually referring to the main page regarding changes of the menu
> > >> structure.
> > >>
> > >> Currently, the layout is:
> > >>
> > >>>    FlinkLogo    |  Overview   | Quickstart  | Features | Download |
> > >> Documentation | FAQ || Blog | Community | Project
> > >>> (-> index.html)  (-> doc page) (-> doc page)                        (->
> > >> doc page)
> > >>
> > >> I would change it to
> > >>
> > >>>    FlinkLogo    | Features | Download | Documentation | FAQ || Blog |
> > >> Community | Project
> > >>> (-> index.html)                         (-> doc page)
> > >>
> > >> With Documentation:
> > >>   - Overview
> > >>   - Quickstart (Setup)
> > >>   - Latest Release (Doc, JavaDoc, ScalaDoc)
> > >>   - Snapshot (Doc, JavaDoc, ScalaDoc)
> > >>   - Wiki
> > >>
> > >> This give the advantage, that only a single menu points to the doc page.
> > >>
> > >> In the doc page, I would keep the Flink logo that points back to the
> > >> main web page.
> > >>
> > >>> FlinkLogo | Overview | Quickstart | Setup | Programming Guides |
> > >> Libraries | Internals
> > >>
> > >> We could split "Programming Guides" into "DataSet API" and "DataStream
> > >> API". The question is about all the other menu point of "Programming
> > >> Guides".
> > >>
> > >> Where to move "Best Practice", "Examples", "Local Execution", "Cluster
> > >> Execution", "Command Line Interface", "Web Client", and "Java 8" ??
> > >>
> > >> => "Python", "Interactive Scale Shell", "Connectors", "Iterations",
> > >> "Hadoop" could go to "DataSet API"
> > >> => "Storm" could go to "DataStream API"
> > >> => as an alternative, "Pyhton", "Hadoop", and "Storm" could go to
> > >> "Libraries" too
> > >>
> > >>
> > >> -Matthias
> > >>
> > >>
> > >>
> > >> On 10/27/2015 11:42 AM, Fabian Hueske wrote:
> > >>> Hi Matthias,
> > >>>
> > >>> thanks for taking care of this issue.
> > >>> How about we change the menu completely, i.e., have menue entries for:
> > >>>
> > >>> - Project Website
> > >>> - Setup
> > >>>   - Local
> > >>>   - Cluster
> > >>>   - Yarn
> > >>> - DataSet API
> > >>>   - Programming guide
> > >>>   - transformations
> > >>> - DataStream API
> > >>>   - Programming Guide
> > >>> - Internals
> > >>>
> > >>> This is not a complete list, just what came to my mind right now.
> > >>>
> > >>> Cheers,
> > >>> Fabian
> > >>>
> > >>> 2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
> > >>>
> > >>>> I started to work on this. Please see here:
> > >>>> https://github.com/mjsax/flink/tree/flink-2752-webpage
> > >>>>
> > >>>> Basically, I just changed the color schema of the menu. I also remove
> > >>>> "How to Contribute" and "Coding Guidelines" from "Internals".
> > >>>>
> > >>>> To get an even better separation, I would like to change the menu from
> > >>>> the main web page, too.
> > >>>>
> > >>>>  - At least we should change the link of "Overview" which is not
> > useful
> > >>>> at all, right now (is it broken or intentionally?)
> > >>>>  - I would also move "Quickstart" as sub-menu point of "Documentation"
> > >>>>  - maybe we could move "Overview" as sub-menu point of
> > "Documentation",
> > >> too
> > >>>>
> > >>>> From my point of view, having a different menu structure and color
> > >>>> should be good enough to make the distinction of both pages clear.
> > >>>>
> > >>>> Btw: the link "setup guide" in *Getting Started* section at the main
> > >>>> page is broken... I would fix this together with those changes (if
> > >>>> accepted).
> > >>>>
> > >>>> Please give feedback.
> > >>>>
> > >>>> -Matthias
> > >>>>
> > >>>> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
> > >>>>> Thanks Matthias for pointing this out. I opened an issue some time
> > ago
> > >>>> with
> > >>>>> a similar description:
> > >> https://issues.apache.org/jira/browse/FLINK-2752
> > >>>>>
> > >>>>> I agree with Fabian and Ufuk that it makes sense to separate the
> > >> website
> > >>>>> and the source repository. However, the distinction between the
> > >>>>> documentation and the homepage should be more clear.
> > >>>>>
> > >>>>> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]>
> > wrote:
> > >>>>>
> > >>>>>>
> > >>>>>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]> wrote:
> > >>>>>>>
> > >>>>>>> The website consists of two parts which are maintained in two
> > >> separate
> > >>>>>>> respositories:
> > >>>>>>>
> > >>>>>>> 1) The project website about features, community, etc.
> > >>>>>>> 2) The documentation of the project
> > >>>>>>>
> > >>>>>>> We have the separation because we want to be able to update source
> > >> and
> > >>>>>>> documentation in one repository to avoid that the documentation
> > gets
> > >>>> out
> > >>>>>> of
> > >>>>>>> sync. The documentation is built every night and hosted at
> > >>>> ci.apache.org
> > >>>>>> to
> > >>>>>>> achieve that.
> > >>>>>>>
> > >>>>>>> IMO, this separation makes sense, because the project website is
> > not
> > >>>>>>> changed very often whereas the documentation should be touched
> > >> whenever
> > >>>>>> the
> > >>>>>>> API or behavior is changed. I think it is very important to have
> > >>>>>>> documentation in sync with the code. In fact, I believe both parts
> > of
> > >>>> the
> > >>>>>>> website should not be related to each other, so they shouldn't be a
> > >> way
> > >>>>>> to
> > >>>>>>> have both parts getting out-of-sync, except for layout / design
> > which
> > >>>> is
> > >>>>>>> nice to have but not crucial. We might even think about changing
> > the
> > >>>>>>> color-scheme of the documentation to make the difference more
> > clear.
> > >>>>>>
> > >>>>>> Yes, Max pointed this out in the beginning. Let’s change the
> > >>>> colors/design
> > >>>>>> to make the distinction clear. The confusion comes from the fact
> > that
> > >>>> they
> > >>>>>> look similar. It only makes sense to assume that they are hosted on
> > >> the
> > >>>>>> same web server etc. But as Fabian said, there are good reasons
> > >> against
> > >>>> it.
> > >>>>>>
> > >>>>>> – Ufuk
> > >>>>>
> > >>>>
> > >>>>
> > >>>
> > >>
> > >>
> > >
> >
> >

[Fabian Hueske-2]

I agree with Max.
Renaming Overview in Documentation and adding a clear link back to the
project website are the most important issues, IMO.


2015-10-28 10:59 GMT+01:00 Maximilian Michels <[hidden email]>:

> We should be careful not to break links to the docs again. I'm in
> favor of making it more clear what is the Flink web site and what its
> documentation is. For me, it would be enough to change "Overview 1.0"
> to "Documentation 1.0" and have a clear link which says "Back to Flink
> website". That should do it.
>
> In the light of the release, all other changes are not that important
> to me right now but I wouldn't deny the structure of the documentation
> can be improved.
>
> On Wed, Oct 28, 2015 at 10:05 AM, Fabian Hueske <[hidden email]> wrote:
> >
> > I agree, two Overview links pointing to different locations should be
> > changed.
> > I am not so sure about the Logo issue. IMO, there should be always a text
> > link. The logo link should only be an addition.
> >
> > Maybe we should wait for more opinions, before we continue.
> > The website has been changed a couple of times, so it would be good to
> get
> > input from those who built the current website, IMO.
> >
> >
> > 2015-10-28 9:56 GMT+01:00 Matthias J. Sax <[hidden email]>:
> >
> > > Yes, but I think that the "Overview" link to index.html is
> > > confusing/wrong. The doc web page has "Overview" too, and it points to
> > > https://ci.apache.org/projects/flink/flink-docs-master/index.html
> > >
> > > There should be only one page with name "Overview" (either on the web
> > > page or on the doc page). I actually thought, that the "Overview" link
> > > from the main page should point to the documentation overview and is
> > > currently just wrong?
> > >
> > > Last but not least, using the Logo and an additional "Overview" menu
> > > point both pointing to the same location is redundant. I would just go
> > > with the logo as a link (or if an explicit menu point is used, disable
> > > the logo as a link -- too me, it is always confusing it two links next
> > > to each other do the same thing).
> > >
> > > -Matthias
> > >
> > >
> > >
> > > On 10/27/2015 11:56 PM, Fabian Hueske wrote:
> > > > I agree that it is confusing that the documentation is linked more
> than
> > > > once from the project website menu. It is not clear when you enter
> the
> > > > documentation section and how to get back.
> > > >
> > > > However, the "Overview" menu entry on the project website does not
> point
> > > to
> > > > the documentation but to http://flink.apache.org/index.html. Hence,
> it
> > > can
> > > > stay in the menu and should not be moved under Documentation.
> > > >
> > > > I would also add a dedicated "Project Website" link to the
> Documentation
> > > > menu in addition to the link on the logo.
> > > >
> > > > 2015-10-27 20:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
> > > >
> > > >> Thanks for the input Fabian!
> > > >>
> > > >> I was actually referring to the main page regarding changes of the
> menu
> > > >> structure.
> > > >>
> > > >> Currently, the layout is:
> > > >>
> > > >>>    FlinkLogo    |  Overview   | Quickstart  | Features | Download |
> > > >> Documentation | FAQ || Blog | Community | Project
> > > >>> (-> index.html)  (-> doc page) (-> doc page)
>   (->
> > > >> doc page)
> > > >>
> > > >> I would change it to
> > > >>
> > > >>>    FlinkLogo    | Features | Download | Documentation | FAQ ||
> Blog |
> > > >> Community | Project
> > > >>> (-> index.html)                         (-> doc page)
> > > >>
> > > >> With Documentation:
> > > >>   - Overview
> > > >>   - Quickstart (Setup)
> > > >>   - Latest Release (Doc, JavaDoc, ScalaDoc)
> > > >>   - Snapshot (Doc, JavaDoc, ScalaDoc)
> > > >>   - Wiki
> > > >>
> > > >> This give the advantage, that only a single menu points to the doc
> page.
> > > >>
> > > >> In the doc page, I would keep the Flink logo that points back to the
> > > >> main web page.
> > > >>
> > > >>> FlinkLogo | Overview | Quickstart | Setup | Programming Guides |
> > > >> Libraries | Internals
> > > >>
> > > >> We could split "Programming Guides" into "DataSet API" and
> "DataStream
> > > >> API". The question is about all the other menu point of "Programming
> > > >> Guides".
> > > >>
> > > >> Where to move "Best Practice", "Examples", "Local Execution",
> "Cluster
> > > >> Execution", "Command Line Interface", "Web Client", and "Java 8" ??
> > > >>
> > > >> => "Python", "Interactive Scale Shell", "Connectors", "Iterations",
> > > >> "Hadoop" could go to "DataSet API"
> > > >> => "Storm" could go to "DataStream API"
> > > >> => as an alternative, "Pyhton", "Hadoop", and "Storm" could go to
> > > >> "Libraries" too
> > > >>
> > > >>
> > > >> -Matthias
> > > >>
> > > >>
> > > >>
> > > >> On 10/27/2015 11:42 AM, Fabian Hueske wrote:
> > > >>> Hi Matthias,
> > > >>>
> > > >>> thanks for taking care of this issue.
> > > >>> How about we change the menu completely, i.e., have menue entries
> for:
> > > >>>
> > > >>> - Project Website
> > > >>> - Setup
> > > >>>   - Local
> > > >>>   - Cluster
> > > >>>   - Yarn
> > > >>> - DataSet API
> > > >>>   - Programming guide
> > > >>>   - transformations
> > > >>> - DataStream API
> > > >>>   - Programming Guide
> > > >>> - Internals
> > > >>>
> > > >>> This is not a complete list, just what came to my mind right now.
> > > >>>
> > > >>> Cheers,
> > > >>> Fabian
> > > >>>
> > > >>> 2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
> > > >>>
> > > >>>> I started to work on this. Please see here:
> > > >>>> https://github.com/mjsax/flink/tree/flink-2752-webpage
> > > >>>>
> > > >>>> Basically, I just changed the color schema of the menu. I also
> remove
> > > >>>> "How to Contribute" and "Coding Guidelines" from "Internals".
> > > >>>>
> > > >>>> To get an even better separation, I would like to change the menu
> from
> > > >>>> the main web page, too.
> > > >>>>
> > > >>>>  - At least we should change the link of "Overview" which is not
> > > useful
> > > >>>> at all, right now (is it broken or intentionally?)
> > > >>>>  - I would also move "Quickstart" as sub-menu point of
> "Documentation"
> > > >>>>  - maybe we could move "Overview" as sub-menu point of
> > > "Documentation",
> > > >> too
> > > >>>>
> > > >>>> From my point of view, having a different menu structure and color
> > > >>>> should be good enough to make the distinction of both pages clear.
> > > >>>>
> > > >>>> Btw: the link "setup guide" in *Getting Started* section at the
> main
> > > >>>> page is broken... I would fix this together with those changes (if
> > > >>>> accepted).
> > > >>>>
> > > >>>> Please give feedback.
> > > >>>>
> > > >>>> -Matthias
> > > >>>>
> > > >>>> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
> > > >>>>> Thanks Matthias for pointing this out. I opened an issue some
> time
> > > ago
> > > >>>> with
> > > >>>>> a similar description:
> > > >> https://issues.apache.org/jira/browse/FLINK-2752
> > > >>>>>
> > > >>>>> I agree with Fabian and Ufuk that it makes sense to separate the
> > > >> website
> > > >>>>> and the source repository. However, the distinction between the
> > > >>>>> documentation and the homepage should be more clear.
> > > >>>>>
> > > >>>>> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]>
> > > wrote:
> > > >>>>>
> > > >>>>>>
> > > >>>>>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]>
> wrote:
> > > >>>>>>>
> > > >>>>>>> The website consists of two parts which are maintained in two
> > > >> separate
> > > >>>>>>> respositories:
> > > >>>>>>>
> > > >>>>>>> 1) The project website about features, community, etc.
> > > >>>>>>> 2) The documentation of the project
> > > >>>>>>>
> > > >>>>>>> We have the separation because we want to be able to update
> source
> > > >> and
> > > >>>>>>> documentation in one repository to avoid that the documentation
> > > gets
> > > >>>> out
> > > >>>>>> of
> > > >>>>>>> sync. The documentation is built every night and hosted at
> > > >>>> ci.apache.org
> > > >>>>>> to
> > > >>>>>>> achieve that.
> > > >>>>>>>
> > > >>>>>>> IMO, this separation makes sense, because the project website
> is
> > > not
> > > >>>>>>> changed very often whereas the documentation should be touched
> > > >> whenever
> > > >>>>>> the
> > > >>>>>>> API or behavior is changed. I think it is very important to
> have
> > > >>>>>>> documentation in sync with the code. In fact, I believe both
> parts
> > > of
> > > >>>> the
> > > >>>>>>> website should not be related to each other, so they shouldn't
> be a
> > > >> way
> > > >>>>>> to
> > > >>>>>>> have both parts getting out-of-sync, except for layout / design
> > > which
> > > >>>> is
> > > >>>>>>> nice to have but not crucial. We might even think about
> changing
> > > the
> > > >>>>>>> color-scheme of the documentation to make the difference more
> > > clear.
> > > >>>>>>
> > > >>>>>> Yes, Max pointed this out in the beginning. Let’s change the
> > > >>>> colors/design
> > > >>>>>> to make the distinction clear. The confusion comes from the fact
> > > that
> > > >>>> they
> > > >>>>>> look similar. It only makes sense to assume that they are
> hosted on
> > > >> the
> > > >>>>>> same web server etc. But as Fabian said, there are good reasons
> > > >> against
> > > >>>> it.
> > > >>>>>>
> > > >>>>>> – Ufuk
> > > >>>>>
> > > >>>>
> > > >>>>
> > > >>>
> > > >>
> > > >>
> > > >
> > >
> > >
>

[Matthias J. Sax-2]

What about "Quickstart" menu point... I really would like to move it
under "Documentation" (to get rid of linking to the doc page on two
places...)

Furthermore, I would suggest to rename "Overview" to "Home" on main page
and keep "Overview" on doc page.

Logo/Text: I am fine with a text-link (but would remove the logo link --
there is no advantage in having it)

If there are no strict objections, I will just update my branch
accordingly, such that everybody can try it out. After that, we can try
to come to a conclusion.

I guess, together with the darker color schema on the doc page menu, the
distinction between both pages should become clear.

-Matthias

On 10/28/2015 11:19 AM, Fabian Hueske wrote:

> I agree with Max.
> Renaming Overview in Documentation and adding a clear link back to the
> project website are the most important issues, IMO.
>
>
> 2015-10-28 10:59 GMT+01:00 Maximilian Michels <[hidden email]>:
>
>> We should be careful not to break links to the docs again. I'm in
>> favor of making it more clear what is the Flink web site and what its
>> documentation is. For me, it would be enough to change "Overview 1.0"
>> to "Documentation 1.0" and have a clear link which says "Back to Flink
>> website". That should do it.
>>
>> In the light of the release, all other changes are not that important
>> to me right now but I wouldn't deny the structure of the documentation
>> can be improved.
>>
>> On Wed, Oct 28, 2015 at 10:05 AM, Fabian Hueske <[hidden email]> wrote:
>>>
>>> I agree, two Overview links pointing to different locations should be
>>> changed.
>>> I am not so sure about the Logo issue. IMO, there should be always a text
>>> link. The logo link should only be an addition.
>>>
>>> Maybe we should wait for more opinions, before we continue.
>>> The website has been changed a couple of times, so it would be good to
>> get
>>> input from those who built the current website, IMO.
>>>
>>>
>>> 2015-10-28 9:56 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>
>>>> Yes, but I think that the "Overview" link to index.html is
>>>> confusing/wrong. The doc web page has "Overview" too, and it points to
>>>> https://ci.apache.org/projects/flink/flink-docs-master/index.html
>>>>
>>>> There should be only one page with name "Overview" (either on the web
>>>> page or on the doc page). I actually thought, that the "Overview" link
>>>> from the main page should point to the documentation overview and is
>>>> currently just wrong?
>>>>
>>>> Last but not least, using the Logo and an additional "Overview" menu
>>>> point both pointing to the same location is redundant. I would just go
>>>> with the logo as a link (or if an explicit menu point is used, disable
>>>> the logo as a link -- too me, it is always confusing it two links next
>>>> to each other do the same thing).
>>>>
>>>> -Matthias
>>>>
>>>>
>>>>
>>>> On 10/27/2015 11:56 PM, Fabian Hueske wrote:
>>>>> I agree that it is confusing that the documentation is linked more
>> than
>>>>> once from the project website menu. It is not clear when you enter
>> the
>>>>> documentation section and how to get back.
>>>>>
>>>>> However, the "Overview" menu entry on the project website does not
>> point
>>>> to
>>>>> the documentation but to http://flink.apache.org/index.html. Hence,
>> it
>>>> can
>>>>> stay in the menu and should not be moved under Documentation.
>>>>>
>>>>> I would also add a dedicated "Project Website" link to the
>> Documentation
>>>>> menu in addition to the link on the logo.
>>>>>
>>>>> 2015-10-27 20:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>>
>>>>>> Thanks for the input Fabian!
>>>>>>
>>>>>> I was actually referring to the main page regarding changes of the
>> menu
>>>>>> structure.
>>>>>>
>>>>>> Currently, the layout is:
>>>>>>
>>>>>>>    FlinkLogo    |  Overview   | Quickstart  | Features | Download |
>>>>>> Documentation | FAQ || Blog | Community | Project
>>>>>>> (-> index.html)  (-> doc page) (-> doc page)
>>   (->
>>>>>> doc page)
>>>>>>
>>>>>> I would change it to
>>>>>>
>>>>>>>    FlinkLogo    | Features | Download | Documentation | FAQ ||
>> Blog |
>>>>>> Community | Project
>>>>>>> (-> index.html)                         (-> doc page)
>>>>>>
>>>>>> With Documentation:
>>>>>>   - Overview
>>>>>>   - Quickstart (Setup)
>>>>>>   - Latest Release (Doc, JavaDoc, ScalaDoc)
>>>>>>   - Snapshot (Doc, JavaDoc, ScalaDoc)
>>>>>>   - Wiki
>>>>>>
>>>>>> This give the advantage, that only a single menu points to the doc
>> page.
>>>>>>
>>>>>> In the doc page, I would keep the Flink logo that points back to the
>>>>>> main web page.
>>>>>>
>>>>>>> FlinkLogo | Overview | Quickstart | Setup | Programming Guides |
>>>>>> Libraries | Internals
>>>>>>
>>>>>> We could split "Programming Guides" into "DataSet API" and
>> "DataStream
>>>>>> API". The question is about all the other menu point of "Programming
>>>>>> Guides".
>>>>>>
>>>>>> Where to move "Best Practice", "Examples", "Local Execution",
>> "Cluster
>>>>>> Execution", "Command Line Interface", "Web Client", and "Java 8" ??
>>>>>>
>>>>>> => "Python", "Interactive Scale Shell", "Connectors", "Iterations",
>>>>>> "Hadoop" could go to "DataSet API"
>>>>>> => "Storm" could go to "DataStream API"
>>>>>> => as an alternative, "Pyhton", "Hadoop", and "Storm" could go to
>>>>>> "Libraries" too
>>>>>>
>>>>>>
>>>>>> -Matthias
>>>>>>
>>>>>>
>>>>>>
>>>>>> On 10/27/2015 11:42 AM, Fabian Hueske wrote:
>>>>>>> Hi Matthias,
>>>>>>>
>>>>>>> thanks for taking care of this issue.
>>>>>>> How about we change the menu completely, i.e., have menue entries
>> for:
>>>>>>>
>>>>>>> - Project Website
>>>>>>> - Setup
>>>>>>>   - Local
>>>>>>>   - Cluster
>>>>>>>   - Yarn
>>>>>>> - DataSet API
>>>>>>>   - Programming guide
>>>>>>>   - transformations
>>>>>>> - DataStream API
>>>>>>>   - Programming Guide
>>>>>>> - Internals
>>>>>>>
>>>>>>> This is not a complete list, just what came to my mind right now.
>>>>>>>
>>>>>>> Cheers,
>>>>>>> Fabian
>>>>>>>
>>>>>>> 2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>>>>
>>>>>>>> I started to work on this. Please see here:
>>>>>>>> https://github.com/mjsax/flink/tree/flink-2752-webpage
>>>>>>>>
>>>>>>>> Basically, I just changed the color schema of the menu. I also
>> remove
>>>>>>>> "How to Contribute" and "Coding Guidelines" from "Internals".
>>>>>>>>
>>>>>>>> To get an even better separation, I would like to change the menu
>> from
>>>>>>>> the main web page, too.
>>>>>>>>
>>>>>>>>  - At least we should change the link of "Overview" which is not
>>>> useful
>>>>>>>> at all, right now (is it broken or intentionally?)
>>>>>>>>  - I would also move "Quickstart" as sub-menu point of
>> "Documentation"
>>>>>>>>  - maybe we could move "Overview" as sub-menu point of
>>>> "Documentation",
>>>>>> too
>>>>>>>>
>>>>>>>> From my point of view, having a different menu structure and color
>>>>>>>> should be good enough to make the distinction of both pages clear.
>>>>>>>>
>>>>>>>> Btw: the link "setup guide" in *Getting Started* section at the
>> main
>>>>>>>> page is broken... I would fix this together with those changes (if
>>>>>>>> accepted).
>>>>>>>>
>>>>>>>> Please give feedback.
>>>>>>>>
>>>>>>>> -Matthias
>>>>>>>>
>>>>>>>> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
>>>>>>>>> Thanks Matthias for pointing this out. I opened an issue some
>> time
>>>> ago
>>>>>>>> with
>>>>>>>>> a similar description:
>>>>>> https://issues.apache.org/jira/browse/FLINK-2752
>>>>>>>>>
>>>>>>>>> I agree with Fabian and Ufuk that it makes sense to separate the
>>>>>> website
>>>>>>>>> and the source repository. However, the distinction between the
>>>>>>>>> documentation and the homepage should be more clear.
>>>>>>>>>
>>>>>>>>> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]>
>>>> wrote:
>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]>
>> wrote:
>>>>>>>>>>>
>>>>>>>>>>> The website consists of two parts which are maintained in two
>>>>>> separate
>>>>>>>>>>> respositories:
>>>>>>>>>>>
>>>>>>>>>>> 1) The project website about features, community, etc.
>>>>>>>>>>> 2) The documentation of the project
>>>>>>>>>>>
>>>>>>>>>>> We have the separation because we want to be able to update
>> source
>>>>>> and
>>>>>>>>>>> documentation in one repository to avoid that the documentation
>>>> gets
>>>>>>>> out
>>>>>>>>>> of
>>>>>>>>>>> sync. The documentation is built every night and hosted at
>>>>>>>> ci.apache.org
>>>>>>>>>> to
>>>>>>>>>>> achieve that.
>>>>>>>>>>>
>>>>>>>>>>> IMO, this separation makes sense, because the project website
>> is
>>>> not
>>>>>>>>>>> changed very often whereas the documentation should be touched
>>>>>> whenever
>>>>>>>>>> the
>>>>>>>>>>> API or behavior is changed. I think it is very important to
>> have
>>>>>>>>>>> documentation in sync with the code. In fact, I believe both
>> parts
>>>> of
>>>>>>>> the
>>>>>>>>>>> website should not be related to each other, so they shouldn't
>> be a
>>>>>> way
>>>>>>>>>> to
>>>>>>>>>>> have both parts getting out-of-sync, except for layout / design
>>>> which
>>>>>>>> is
>>>>>>>>>>> nice to have but not crucial. We might even think about
>> changing
>>>> the
>>>>>>>>>>> color-scheme of the documentation to make the difference more
>>>> clear.
>>>>>>>>>>
>>>>>>>>>> Yes, Max pointed this out in the beginning. Let’s change the
>>>>>>>> colors/design
>>>>>>>>>> to make the distinction clear. The confusion comes from the fact
>>>> that
>>>>>>>> they
>>>>>>>>>> look similar. It only makes sense to assume that they are
>> hosted on
>>>>>> the
>>>>>>>>>> same web server etc. But as Fabian said, there are good reasons
>>>>>> against
>>>>>>>> it.
>>>>>>>>>>
>>>>>>>>>> – Ufuk
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>>
>>>>
>>
>

[Aljoscha Krettek-2]

I think the quickstarts should be very easy to discover, so we should keep them on the main page. If you just browse to flink.apache.org you would not be aware that they exist.

> On 28 Oct 2015, at 13:37, Matthias J. Sax <[hidden email]> wrote:
>
> What about "Quickstart" menu point... I really would like to move it
> under "Documentation" (to get rid of linking to the doc page on two
> places...)
>
> Furthermore, I would suggest to rename "Overview" to "Home" on main page
> and keep "Overview" on doc page.
>
> Logo/Text: I am fine with a text-link (but would remove the logo link --
> there is no advantage in having it)
>
> If there are no strict objections, I will just update my branch
> accordingly, such that everybody can try it out. After that, we can try
> to come to a conclusion.
>
> I guess, together with the darker color schema on the doc page menu, the
> distinction between both pages should become clear.
>
> -Matthias
>
> On 10/28/2015 11:19 AM, Fabian Hueske wrote:
>> I agree with Max.
>> Renaming Overview in Documentation and adding a clear link back to the
>> project website are the most important issues, IMO.
>>
>>
>> 2015-10-28 10:59 GMT+01:00 Maximilian Michels <[hidden email]>:
>>
>>> We should be careful not to break links to the docs again. I'm in
>>> favor of making it more clear what is the Flink web site and what its
>>> documentation is. For me, it would be enough to change "Overview 1.0"
>>> to "Documentation 1.0" and have a clear link which says "Back to Flink
>>> website". That should do it.
>>>
>>> In the light of the release, all other changes are not that important
>>> to me right now but I wouldn't deny the structure of the documentation
>>> can be improved.
>>>
>>> On Wed, Oct 28, 2015 at 10:05 AM, Fabian Hueske <[hidden email]> wrote:
>>>>
>>>> I agree, two Overview links pointing to different locations should be
>>>> changed.
>>>> I am not so sure about the Logo issue. IMO, there should be always a text
>>>> link. The logo link should only be an addition.
>>>>
>>>> Maybe we should wait for more opinions, before we continue.
>>>> The website has been changed a couple of times, so it would be good to
>>> get
>>>> input from those who built the current website, IMO.
>>>>
>>>>
>>>> 2015-10-28 9:56 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>
>>>>> Yes, but I think that the "Overview" link to index.html is
>>>>> confusing/wrong. The doc web page has "Overview" too, and it points to
>>>>> https://ci.apache.org/projects/flink/flink-docs-master/index.html
>>>>>
>>>>> There should be only one page with name "Overview" (either on the web
>>>>> page or on the doc page). I actually thought, that the "Overview" link
>>>>> from the main page should point to the documentation overview and is
>>>>> currently just wrong?
>>>>>
>>>>> Last but not least, using the Logo and an additional "Overview" menu
>>>>> point both pointing to the same location is redundant. I would just go
>>>>> with the logo as a link (or if an explicit menu point is used, disable
>>>>> the logo as a link -- too me, it is always confusing it two links next
>>>>> to each other do the same thing).
>>>>>
>>>>> -Matthias
>>>>>
>>>>>
>>>>>
>>>>> On 10/27/2015 11:56 PM, Fabian Hueske wrote:
>>>>>> I agree that it is confusing that the documentation is linked more
>>> than
>>>>>> once from the project website menu. It is not clear when you enter
>>> the
>>>>>> documentation section and how to get back.
>>>>>>
>>>>>> However, the "Overview" menu entry on the project website does not
>>> point
>>>>> to
>>>>>> the documentation but to http://flink.apache.org/index.html. Hence,
>>> it
>>>>> can
>>>>>> stay in the menu and should not be moved under Documentation.
>>>>>>
>>>>>> I would also add a dedicated "Project Website" link to the
>>> Documentation
>>>>>> menu in addition to the link on the logo.
>>>>>>
>>>>>> 2015-10-27 20:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>>>
>>>>>>> Thanks for the input Fabian!
>>>>>>>
>>>>>>> I was actually referring to the main page regarding changes of the
>>> menu
>>>>>>> structure.
>>>>>>>
>>>>>>> Currently, the layout is:
>>>>>>>
>>>>>>>>   FlinkLogo    |  Overview   | Quickstart  | Features | Download |
>>>>>>> Documentation | FAQ || Blog | Community | Project
>>>>>>>> (-> index.html)  (-> doc page) (-> doc page)
>>>  (->
>>>>>>> doc page)
>>>>>>>
>>>>>>> I would change it to
>>>>>>>
>>>>>>>>   FlinkLogo    | Features | Download | Documentation | FAQ ||
>>> Blog |
>>>>>>> Community | Project
>>>>>>>> (-> index.html)                         (-> doc page)
>>>>>>>
>>>>>>> With Documentation:
>>>>>>>  - Overview
>>>>>>>  - Quickstart (Setup)
>>>>>>>  - Latest Release (Doc, JavaDoc, ScalaDoc)
>>>>>>>  - Snapshot (Doc, JavaDoc, ScalaDoc)
>>>>>>>  - Wiki
>>>>>>>
>>>>>>> This give the advantage, that only a single menu points to the doc
>>> page.
>>>>>>>
>>>>>>> In the doc page, I would keep the Flink logo that points back to the
>>>>>>> main web page.
>>>>>>>
>>>>>>>> FlinkLogo | Overview | Quickstart | Setup | Programming Guides |
>>>>>>> Libraries | Internals
>>>>>>>
>>>>>>> We could split "Programming Guides" into "DataSet API" and
>>> "DataStream
>>>>>>> API". The question is about all the other menu point of "Programming
>>>>>>> Guides".
>>>>>>>
>>>>>>> Where to move "Best Practice", "Examples", "Local Execution",
>>> "Cluster
>>>>>>> Execution", "Command Line Interface", "Web Client", and "Java 8" ??
>>>>>>>
>>>>>>> => "Python", "Interactive Scale Shell", "Connectors", "Iterations",
>>>>>>> "Hadoop" could go to "DataSet API"
>>>>>>> => "Storm" could go to "DataStream API"
>>>>>>> => as an alternative, "Pyhton", "Hadoop", and "Storm" could go to
>>>>>>> "Libraries" too
>>>>>>>
>>>>>>>
>>>>>>> -Matthias
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> On 10/27/2015 11:42 AM, Fabian Hueske wrote:
>>>>>>>> Hi Matthias,
>>>>>>>>
>>>>>>>> thanks for taking care of this issue.
>>>>>>>> How about we change the menu completely, i.e., have menue entries
>>> for:
>>>>>>>>
>>>>>>>> - Project Website
>>>>>>>> - Setup
>>>>>>>>  - Local
>>>>>>>>  - Cluster
>>>>>>>>  - Yarn
>>>>>>>> - DataSet API
>>>>>>>>  - Programming guide
>>>>>>>>  - transformations
>>>>>>>> - DataStream API
>>>>>>>>  - Programming Guide
>>>>>>>> - Internals
>>>>>>>>
>>>>>>>> This is not a complete list, just what came to my mind right now.
>>>>>>>>
>>>>>>>> Cheers,
>>>>>>>> Fabian
>>>>>>>>
>>>>>>>> 2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>>>>>
>>>>>>>>> I started to work on this. Please see here:
>>>>>>>>> https://github.com/mjsax/flink/tree/flink-2752-webpage
>>>>>>>>>
>>>>>>>>> Basically, I just changed the color schema of the menu. I also
>>> remove
>>>>>>>>> "How to Contribute" and "Coding Guidelines" from "Internals".
>>>>>>>>>
>>>>>>>>> To get an even better separation, I would like to change the menu
>>> from
>>>>>>>>> the main web page, too.
>>>>>>>>>
>>>>>>>>> - At least we should change the link of "Overview" which is not
>>>>> useful
>>>>>>>>> at all, right now (is it broken or intentionally?)
>>>>>>>>> - I would also move "Quickstart" as sub-menu point of
>>> "Documentation"
>>>>>>>>> - maybe we could move "Overview" as sub-menu point of
>>>>> "Documentation",
>>>>>>> too
>>>>>>>>>
>>>>>>>>> From my point of view, having a different menu structure and color
>>>>>>>>> should be good enough to make the distinction of both pages clear.
>>>>>>>>>
>>>>>>>>> Btw: the link "setup guide" in *Getting Started* section at the
>>> main
>>>>>>>>> page is broken... I would fix this together with those changes (if
>>>>>>>>> accepted).
>>>>>>>>>
>>>>>>>>> Please give feedback.
>>>>>>>>>
>>>>>>>>> -Matthias
>>>>>>>>>
>>>>>>>>> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
>>>>>>>>>> Thanks Matthias for pointing this out. I opened an issue some
>>> time
>>>>> ago
>>>>>>>>> with
>>>>>>>>>> a similar description:
>>>>>>> https://issues.apache.org/jira/browse/FLINK-2752
>>>>>>>>>>
>>>>>>>>>> I agree with Fabian and Ufuk that it makes sense to separate the
>>>>>>> website
>>>>>>>>>> and the source repository. However, the distinction between the
>>>>>>>>>> documentation and the homepage should be more clear.
>>>>>>>>>>
>>>>>>>>>> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]>
>>>>> wrote:
>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]>
>>> wrote:
>>>>>>>>>>>>
>>>>>>>>>>>> The website consists of two parts which are maintained in two
>>>>>>> separate
>>>>>>>>>>>> respositories:
>>>>>>>>>>>>
>>>>>>>>>>>> 1) The project website about features, community, etc.
>>>>>>>>>>>> 2) The documentation of the project
>>>>>>>>>>>>
>>>>>>>>>>>> We have the separation because we want to be able to update
>>> source
>>>>>>> and
>>>>>>>>>>>> documentation in one repository to avoid that the documentation
>>>>> gets
>>>>>>>>> out
>>>>>>>>>>> of
>>>>>>>>>>>> sync. The documentation is built every night and hosted at
>>>>>>>>> ci.apache.org
>>>>>>>>>>> to
>>>>>>>>>>>> achieve that.
>>>>>>>>>>>>
>>>>>>>>>>>> IMO, this separation makes sense, because the project website
>>> is
>>>>> not
>>>>>>>>>>>> changed very often whereas the documentation should be touched
>>>>>>> whenever
>>>>>>>>>>> the
>>>>>>>>>>>> API or behavior is changed. I think it is very important to
>>> have
>>>>>>>>>>>> documentation in sync with the code. In fact, I believe both
>>> parts
>>>>> of
>>>>>>>>> the
>>>>>>>>>>>> website should not be related to each other, so they shouldn't
>>> be a
>>>>>>> way
>>>>>>>>>>> to
>>>>>>>>>>>> have both parts getting out-of-sync, except for layout / design
>>>>> which
>>>>>>>>> is
>>>>>>>>>>>> nice to have but not crucial. We might even think about
>>> changing
>>>>> the
>>>>>>>>>>>> color-scheme of the documentation to make the difference more
>>>>> clear.
>>>>>>>>>>>
>>>>>>>>>>> Yes, Max pointed this out in the beginning. Let’s change the
>>>>>>>>> colors/design
>>>>>>>>>>> to make the distinction clear. The confusion comes from the fact
>>>>> that
>>>>>>>>> they
>>>>>>>>>>> look similar. It only makes sense to assume that they are
>>> hosted on
>>>>>>> the
>>>>>>>>>>> same web server etc. But as Fabian said, there are good reasons
>>>>>>> against
>>>>>>>>> it.
>>>>>>>>>>>
>>>>>>>>>>> – Ufuk
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>>
>>>>>
>>>
>>
>

[Matthias J. Sax-2]

Good point.

How often does "Quickstart" change? Seems to be fairly stable. Maybe we
could move it from doc page to main page?

Btw: The link "Flink on Windows" is broken in the Quickstart guide.

-Matthias

On 10/28/2015 02:09 PM, Aljoscha Krettek wrote:

> I think the quickstarts should be very easy to discover, so we should keep them on the main page. If you just browse to flink.apache.org you would not be aware that they exist.
>> On 28 Oct 2015, at 13:37, Matthias J. Sax <[hidden email]> wrote:
>>
>> What about "Quickstart" menu point... I really would like to move it
>> under "Documentation" (to get rid of linking to the doc page on two
>> places...)
>>
>> Furthermore, I would suggest to rename "Overview" to "Home" on main page
>> and keep "Overview" on doc page.
>>
>> Logo/Text: I am fine with a text-link (but would remove the logo link --
>> there is no advantage in having it)
>>
>> If there are no strict objections, I will just update my branch
>> accordingly, such that everybody can try it out. After that, we can try
>> to come to a conclusion.
>>
>> I guess, together with the darker color schema on the doc page menu, the
>> distinction between both pages should become clear.
>>
>> -Matthias
>>
>> On 10/28/2015 11:19 AM, Fabian Hueske wrote:
>>> I agree with Max.
>>> Renaming Overview in Documentation and adding a clear link back to the
>>> project website are the most important issues, IMO.
>>>
>>>
>>> 2015-10-28 10:59 GMT+01:00 Maximilian Michels <[hidden email]>:
>>>
>>>> We should be careful not to break links to the docs again. I'm in
>>>> favor of making it more clear what is the Flink web site and what its
>>>> documentation is. For me, it would be enough to change "Overview 1.0"
>>>> to "Documentation 1.0" and have a clear link which says "Back to Flink
>>>> website". That should do it.
>>>>
>>>> In the light of the release, all other changes are not that important
>>>> to me right now but I wouldn't deny the structure of the documentation
>>>> can be improved.
>>>>
>>>> On Wed, Oct 28, 2015 at 10:05 AM, Fabian Hueske <[hidden email]> wrote:
>>>>>
>>>>> I agree, two Overview links pointing to different locations should be
>>>>> changed.
>>>>> I am not so sure about the Logo issue. IMO, there should be always a text
>>>>> link. The logo link should only be an addition.
>>>>>
>>>>> Maybe we should wait for more opinions, before we continue.
>>>>> The website has been changed a couple of times, so it would be good to
>>>> get
>>>>> input from those who built the current website, IMO.
>>>>>
>>>>>
>>>>> 2015-10-28 9:56 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>>
>>>>>> Yes, but I think that the "Overview" link to index.html is
>>>>>> confusing/wrong. The doc web page has "Overview" too, and it points to
>>>>>> https://ci.apache.org/projects/flink/flink-docs-master/index.html
>>>>>>
>>>>>> There should be only one page with name "Overview" (either on the web
>>>>>> page or on the doc page). I actually thought, that the "Overview" link
>>>>>> from the main page should point to the documentation overview and is
>>>>>> currently just wrong?
>>>>>>
>>>>>> Last but not least, using the Logo and an additional "Overview" menu
>>>>>> point both pointing to the same location is redundant. I would just go
>>>>>> with the logo as a link (or if an explicit menu point is used, disable
>>>>>> the logo as a link -- too me, it is always confusing it two links next
>>>>>> to each other do the same thing).
>>>>>>
>>>>>> -Matthias
>>>>>>
>>>>>>
>>>>>>
>>>>>> On 10/27/2015 11:56 PM, Fabian Hueske wrote:
>>>>>>> I agree that it is confusing that the documentation is linked more
>>>> than
>>>>>>> once from the project website menu. It is not clear when you enter
>>>> the
>>>>>>> documentation section and how to get back.
>>>>>>>
>>>>>>> However, the "Overview" menu entry on the project website does not
>>>> point
>>>>>> to
>>>>>>> the documentation but to http://flink.apache.org/index.html. Hence,
>>>> it
>>>>>> can
>>>>>>> stay in the menu and should not be moved under Documentation.
>>>>>>>
>>>>>>> I would also add a dedicated "Project Website" link to the
>>>> Documentation
>>>>>>> menu in addition to the link on the logo.
>>>>>>>
>>>>>>> 2015-10-27 20:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>>>>
>>>>>>>> Thanks for the input Fabian!
>>>>>>>>
>>>>>>>> I was actually referring to the main page regarding changes of the
>>>> menu
>>>>>>>> structure.
>>>>>>>>
>>>>>>>> Currently, the layout is:
>>>>>>>>
>>>>>>>>>   FlinkLogo    |  Overview   | Quickstart  | Features | Download |
>>>>>>>> Documentation | FAQ || Blog | Community | Project
>>>>>>>>> (-> index.html)  (-> doc page) (-> doc page)
>>>>  (->
>>>>>>>> doc page)
>>>>>>>>
>>>>>>>> I would change it to
>>>>>>>>
>>>>>>>>>   FlinkLogo    | Features | Download | Documentation | FAQ ||
>>>> Blog |
>>>>>>>> Community | Project
>>>>>>>>> (-> index.html)                         (-> doc page)
>>>>>>>>
>>>>>>>> With Documentation:
>>>>>>>>  - Overview
>>>>>>>>  - Quickstart (Setup)
>>>>>>>>  - Latest Release (Doc, JavaDoc, ScalaDoc)
>>>>>>>>  - Snapshot (Doc, JavaDoc, ScalaDoc)
>>>>>>>>  - Wiki
>>>>>>>>
>>>>>>>> This give the advantage, that only a single menu points to the doc
>>>> page.
>>>>>>>>
>>>>>>>> In the doc page, I would keep the Flink logo that points back to the
>>>>>>>> main web page.
>>>>>>>>
>>>>>>>>> FlinkLogo | Overview | Quickstart | Setup | Programming Guides |
>>>>>>>> Libraries | Internals
>>>>>>>>
>>>>>>>> We could split "Programming Guides" into "DataSet API" and
>>>> "DataStream
>>>>>>>> API". The question is about all the other menu point of "Programming
>>>>>>>> Guides".
>>>>>>>>
>>>>>>>> Where to move "Best Practice", "Examples", "Local Execution",
>>>> "Cluster
>>>>>>>> Execution", "Command Line Interface", "Web Client", and "Java 8" ??
>>>>>>>>
>>>>>>>> => "Python", "Interactive Scale Shell", "Connectors", "Iterations",
>>>>>>>> "Hadoop" could go to "DataSet API"
>>>>>>>> => "Storm" could go to "DataStream API"
>>>>>>>> => as an alternative, "Pyhton", "Hadoop", and "Storm" could go to
>>>>>>>> "Libraries" too
>>>>>>>>
>>>>>>>>
>>>>>>>> -Matthias
>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> On 10/27/2015 11:42 AM, Fabian Hueske wrote:
>>>>>>>>> Hi Matthias,
>>>>>>>>>
>>>>>>>>> thanks for taking care of this issue.
>>>>>>>>> How about we change the menu completely, i.e., have menue entries
>>>> for:
>>>>>>>>>
>>>>>>>>> - Project Website
>>>>>>>>> - Setup
>>>>>>>>>  - Local
>>>>>>>>>  - Cluster
>>>>>>>>>  - Yarn
>>>>>>>>> - DataSet API
>>>>>>>>>  - Programming guide
>>>>>>>>>  - transformations
>>>>>>>>> - DataStream API
>>>>>>>>>  - Programming Guide
>>>>>>>>> - Internals
>>>>>>>>>
>>>>>>>>> This is not a complete list, just what came to my mind right now.
>>>>>>>>>
>>>>>>>>> Cheers,
>>>>>>>>> Fabian
>>>>>>>>>
>>>>>>>>> 2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>>>>>>
>>>>>>>>>> I started to work on this. Please see here:
>>>>>>>>>> https://github.com/mjsax/flink/tree/flink-2752-webpage
>>>>>>>>>>
>>>>>>>>>> Basically, I just changed the color schema of the menu. I also
>>>> remove
>>>>>>>>>> "How to Contribute" and "Coding Guidelines" from "Internals".
>>>>>>>>>>
>>>>>>>>>> To get an even better separation, I would like to change the menu
>>>> from
>>>>>>>>>> the main web page, too.
>>>>>>>>>>
>>>>>>>>>> - At least we should change the link of "Overview" which is not
>>>>>> useful
>>>>>>>>>> at all, right now (is it broken or intentionally?)
>>>>>>>>>> - I would also move "Quickstart" as sub-menu point of
>>>> "Documentation"
>>>>>>>>>> - maybe we could move "Overview" as sub-menu point of
>>>>>> "Documentation",
>>>>>>>> too
>>>>>>>>>>
>>>>>>>>>> From my point of view, having a different menu structure and color
>>>>>>>>>> should be good enough to make the distinction of both pages clear.
>>>>>>>>>>
>>>>>>>>>> Btw: the link "setup guide" in *Getting Started* section at the
>>>> main
>>>>>>>>>> page is broken... I would fix this together with those changes (if
>>>>>>>>>> accepted).
>>>>>>>>>>
>>>>>>>>>> Please give feedback.
>>>>>>>>>>
>>>>>>>>>> -Matthias
>>>>>>>>>>
>>>>>>>>>> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
>>>>>>>>>>> Thanks Matthias for pointing this out. I opened an issue some
>>>> time
>>>>>> ago
>>>>>>>>>> with
>>>>>>>>>>> a similar description:
>>>>>>>> https://issues.apache.org/jira/browse/FLINK-2752
>>>>>>>>>>>
>>>>>>>>>>> I agree with Fabian and Ufuk that it makes sense to separate the
>>>>>>>> website
>>>>>>>>>>> and the source repository. However, the distinction between the
>>>>>>>>>>> documentation and the homepage should be more clear.
>>>>>>>>>>>
>>>>>>>>>>> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]>
>>>>>> wrote:
>>>>>>>>>>>
>>>>>>>>>>>>
>>>>>>>>>>>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]>
>>>> wrote:
>>>>>>>>>>>>>
>>>>>>>>>>>>> The website consists of two parts which are maintained in two
>>>>>>>> separate
>>>>>>>>>>>>> respositories:
>>>>>>>>>>>>>
>>>>>>>>>>>>> 1) The project website about features, community, etc.
>>>>>>>>>>>>> 2) The documentation of the project
>>>>>>>>>>>>>
>>>>>>>>>>>>> We have the separation because we want to be able to update
>>>> source
>>>>>>>> and
>>>>>>>>>>>>> documentation in one repository to avoid that the documentation
>>>>>> gets
>>>>>>>>>> out
>>>>>>>>>>>> of
>>>>>>>>>>>>> sync. The documentation is built every night and hosted at
>>>>>>>>>> ci.apache.org
>>>>>>>>>>>> to
>>>>>>>>>>>>> achieve that.
>>>>>>>>>>>>>
>>>>>>>>>>>>> IMO, this separation makes sense, because the project website
>>>> is
>>>>>> not
>>>>>>>>>>>>> changed very often whereas the documentation should be touched
>>>>>>>> whenever
>>>>>>>>>>>> the
>>>>>>>>>>>>> API or behavior is changed. I think it is very important to
>>>> have
>>>>>>>>>>>>> documentation in sync with the code. In fact, I believe both
>>>> parts
>>>>>> of
>>>>>>>>>> the
>>>>>>>>>>>>> website should not be related to each other, so they shouldn't
>>>> be a
>>>>>>>> way
>>>>>>>>>>>> to
>>>>>>>>>>>>> have both parts getting out-of-sync, except for layout / design
>>>>>> which
>>>>>>>>>> is
>>>>>>>>>>>>> nice to have but not crucial. We might even think about
>>>> changing
>>>>>> the
>>>>>>>>>>>>> color-scheme of the documentation to make the difference more
>>>>>> clear.
>>>>>>>>>>>>
>>>>>>>>>>>> Yes, Max pointed this out in the beginning. Let’s change the
>>>>>>>>>> colors/design
>>>>>>>>>>>> to make the distinction clear. The confusion comes from the fact
>>>>>> that
>>>>>>>>>> they
>>>>>>>>>>>> look similar. It only makes sense to assume that they are
>>>> hosted on
>>>>>>>> the
>>>>>>>>>>>> same web server etc. But as Fabian said, there are good reasons
>>>>>>>> against
>>>>>>>>>> it.
>>>>>>>>>>>>
>>>>>>>>>>>> – Ufuk
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>
>>>>>>
>>>>
>>>
>>
>

[mxm]

+1 for keeping the Quickstart on the main page but I'm against
removing it from the documentation because it is, essentially, a part
of the documentation.

On Wed, Oct 28, 2015 at 2:25 PM, Matthias J. Sax <[hidden email]> wrote:

> Good point.
>
> How often does "Quickstart" change? Seems to be fairly stable. Maybe we
> could move it from doc page to main page?
>
> Btw: The link "Flink on Windows" is broken in the Quickstart guide.
>
> -Matthias
>
> On 10/28/2015 02:09 PM, Aljoscha Krettek wrote:
>> I think the quickstarts should be very easy to discover, so we should keep them on the main page. If you just browse to flink.apache.org you would not be aware that they exist.
>>> On 28 Oct 2015, at 13:37, Matthias J. Sax <[hidden email]> wrote:
>>>
>>> What about "Quickstart" menu point... I really would like to move it
>>> under "Documentation" (to get rid of linking to the doc page on two
>>> places...)
>>>
>>> Furthermore, I would suggest to rename "Overview" to "Home" on main page
>>> and keep "Overview" on doc page.
>>>
>>> Logo/Text: I am fine with a text-link (but would remove the logo link --
>>> there is no advantage in having it)
>>>
>>> If there are no strict objections, I will just update my branch
>>> accordingly, such that everybody can try it out. After that, we can try
>>> to come to a conclusion.
>>>
>>> I guess, together with the darker color schema on the doc page menu, the
>>> distinction between both pages should become clear.
>>>
>>> -Matthias
>>>
>>> On 10/28/2015 11:19 AM, Fabian Hueske wrote:
>>>> I agree with Max.
>>>> Renaming Overview in Documentation and adding a clear link back to the
>>>> project website are the most important issues, IMO.
>>>>
>>>>
>>>> 2015-10-28 10:59 GMT+01:00 Maximilian Michels <[hidden email]>:
>>>>
>>>>> We should be careful not to break links to the docs again. I'm in
>>>>> favor of making it more clear what is the Flink web site and what its
>>>>> documentation is. For me, it would be enough to change "Overview 1.0"
>>>>> to "Documentation 1.0" and have a clear link which says "Back to Flink
>>>>> website". That should do it.
>>>>>
>>>>> In the light of the release, all other changes are not that important
>>>>> to me right now but I wouldn't deny the structure of the documentation
>>>>> can be improved.
>>>>>
>>>>> On Wed, Oct 28, 2015 at 10:05 AM, Fabian Hueske <[hidden email]> wrote:
>>>>>>
>>>>>> I agree, two Overview links pointing to different locations should be
>>>>>> changed.
>>>>>> I am not so sure about the Logo issue. IMO, there should be always a text
>>>>>> link. The logo link should only be an addition.
>>>>>>
>>>>>> Maybe we should wait for more opinions, before we continue.
>>>>>> The website has been changed a couple of times, so it would be good to
>>>>> get
>>>>>> input from those who built the current website, IMO.
>>>>>>
>>>>>>
>>>>>> 2015-10-28 9:56 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>>>
>>>>>>> Yes, but I think that the "Overview" link to index.html is
>>>>>>> confusing/wrong. The doc web page has "Overview" too, and it points to
>>>>>>> https://ci.apache.org/projects/flink/flink-docs-master/index.html
>>>>>>>
>>>>>>> There should be only one page with name "Overview" (either on the web
>>>>>>> page or on the doc page). I actually thought, that the "Overview" link
>>>>>>> from the main page should point to the documentation overview and is
>>>>>>> currently just wrong?
>>>>>>>
>>>>>>> Last but not least, using the Logo and an additional "Overview" menu
>>>>>>> point both pointing to the same location is redundant. I would just go
>>>>>>> with the logo as a link (or if an explicit menu point is used, disable
>>>>>>> the logo as a link -- too me, it is always confusing it two links next
>>>>>>> to each other do the same thing).
>>>>>>>
>>>>>>> -Matthias
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> On 10/27/2015 11:56 PM, Fabian Hueske wrote:
>>>>>>>> I agree that it is confusing that the documentation is linked more
>>>>> than
>>>>>>>> once from the project website menu. It is not clear when you enter
>>>>> the
>>>>>>>> documentation section and how to get back.
>>>>>>>>
>>>>>>>> However, the "Overview" menu entry on the project website does not
>>>>> point
>>>>>>> to
>>>>>>>> the documentation but to http://flink.apache.org/index.html. Hence,
>>>>> it
>>>>>>> can
>>>>>>>> stay in the menu and should not be moved under Documentation.
>>>>>>>>
>>>>>>>> I would also add a dedicated "Project Website" link to the
>>>>> Documentation
>>>>>>>> menu in addition to the link on the logo.
>>>>>>>>
>>>>>>>> 2015-10-27 20:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>>>>>
>>>>>>>>> Thanks for the input Fabian!
>>>>>>>>>
>>>>>>>>> I was actually referring to the main page regarding changes of the
>>>>> menu
>>>>>>>>> structure.
>>>>>>>>>
>>>>>>>>> Currently, the layout is:
>>>>>>>>>
>>>>>>>>>>   FlinkLogo    |  Overview   | Quickstart  | Features | Download |
>>>>>>>>> Documentation | FAQ || Blog | Community | Project
>>>>>>>>>> (-> index.html)  (-> doc page) (-> doc page)
>>>>>  (->
>>>>>>>>> doc page)
>>>>>>>>>
>>>>>>>>> I would change it to
>>>>>>>>>
>>>>>>>>>>   FlinkLogo    | Features | Download | Documentation | FAQ ||
>>>>> Blog |
>>>>>>>>> Community | Project
>>>>>>>>>> (-> index.html)                         (-> doc page)
>>>>>>>>>
>>>>>>>>> With Documentation:
>>>>>>>>>  - Overview
>>>>>>>>>  - Quickstart (Setup)
>>>>>>>>>  - Latest Release (Doc, JavaDoc, ScalaDoc)
>>>>>>>>>  - Snapshot (Doc, JavaDoc, ScalaDoc)
>>>>>>>>>  - Wiki
>>>>>>>>>
>>>>>>>>> This give the advantage, that only a single menu points to the doc
>>>>> page.
>>>>>>>>>
>>>>>>>>> In the doc page, I would keep the Flink logo that points back to the
>>>>>>>>> main web page.
>>>>>>>>>
>>>>>>>>>> FlinkLogo | Overview | Quickstart | Setup | Programming Guides |
>>>>>>>>> Libraries | Internals
>>>>>>>>>
>>>>>>>>> We could split "Programming Guides" into "DataSet API" and
>>>>> "DataStream
>>>>>>>>> API". The question is about all the other menu point of "Programming
>>>>>>>>> Guides".
>>>>>>>>>
>>>>>>>>> Where to move "Best Practice", "Examples", "Local Execution",
>>>>> "Cluster
>>>>>>>>> Execution", "Command Line Interface", "Web Client", and "Java 8" ??
>>>>>>>>>
>>>>>>>>> => "Python", "Interactive Scale Shell", "Connectors", "Iterations",
>>>>>>>>> "Hadoop" could go to "DataSet API"
>>>>>>>>> => "Storm" could go to "DataStream API"
>>>>>>>>> => as an alternative, "Pyhton", "Hadoop", and "Storm" could go to
>>>>>>>>> "Libraries" too
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> -Matthias
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On 10/27/2015 11:42 AM, Fabian Hueske wrote:
>>>>>>>>>> Hi Matthias,
>>>>>>>>>>
>>>>>>>>>> thanks for taking care of this issue.
>>>>>>>>>> How about we change the menu completely, i.e., have menue entries
>>>>> for:
>>>>>>>>>>
>>>>>>>>>> - Project Website
>>>>>>>>>> - Setup
>>>>>>>>>>  - Local
>>>>>>>>>>  - Cluster
>>>>>>>>>>  - Yarn
>>>>>>>>>> - DataSet API
>>>>>>>>>>  - Programming guide
>>>>>>>>>>  - transformations
>>>>>>>>>> - DataStream API
>>>>>>>>>>  - Programming Guide
>>>>>>>>>> - Internals
>>>>>>>>>>
>>>>>>>>>> This is not a complete list, just what came to my mind right now.
>>>>>>>>>>
>>>>>>>>>> Cheers,
>>>>>>>>>> Fabian
>>>>>>>>>>
>>>>>>>>>> 2015-10-27 3:39 GMT+01:00 Matthias J. Sax <[hidden email]>:
>>>>>>>>>>
>>>>>>>>>>> I started to work on this. Please see here:
>>>>>>>>>>> https://github.com/mjsax/flink/tree/flink-2752-webpage
>>>>>>>>>>>
>>>>>>>>>>> Basically, I just changed the color schema of the menu. I also
>>>>> remove
>>>>>>>>>>> "How to Contribute" and "Coding Guidelines" from "Internals".
>>>>>>>>>>>
>>>>>>>>>>> To get an even better separation, I would like to change the menu
>>>>> from
>>>>>>>>>>> the main web page, too.
>>>>>>>>>>>
>>>>>>>>>>> - At least we should change the link of "Overview" which is not
>>>>>>> useful
>>>>>>>>>>> at all, right now (is it broken or intentionally?)
>>>>>>>>>>> - I would also move "Quickstart" as sub-menu point of
>>>>> "Documentation"
>>>>>>>>>>> - maybe we could move "Overview" as sub-menu point of
>>>>>>> "Documentation",
>>>>>>>>> too
>>>>>>>>>>>
>>>>>>>>>>> From my point of view, having a different menu structure and color
>>>>>>>>>>> should be good enough to make the distinction of both pages clear.
>>>>>>>>>>>
>>>>>>>>>>> Btw: the link "setup guide" in *Getting Started* section at the
>>>>> main
>>>>>>>>>>> page is broken... I would fix this together with those changes (if
>>>>>>>>>>> accepted).
>>>>>>>>>>>
>>>>>>>>>>> Please give feedback.
>>>>>>>>>>>
>>>>>>>>>>> -Matthias
>>>>>>>>>>>
>>>>>>>>>>> On 10/26/2015 10:40 AM, Maximilian Michels wrote:
>>>>>>>>>>>> Thanks Matthias for pointing this out. I opened an issue some
>>>>> time
>>>>>>> ago
>>>>>>>>>>> with
>>>>>>>>>>>> a similar description:
>>>>>>>>> https://issues.apache.org/jira/browse/FLINK-2752
>>>>>>>>>>>>
>>>>>>>>>>>> I agree with Fabian and Ufuk that it makes sense to separate the
>>>>>>>>> website
>>>>>>>>>>>> and the source repository. However, the distinction between the
>>>>>>>>>>>> documentation and the homepage should be more clear.
>>>>>>>>>>>>
>>>>>>>>>>>> On Mon, Oct 26, 2015 at 10:35 AM, Ufuk Celebi <[hidden email]>
>>>>>>> wrote:
>>>>>>>>>>>>
>>>>>>>>>>>>>
>>>>>>>>>>>>>> On 26 Oct 2015, at 10:27, Fabian Hueske <[hidden email]>
>>>>> wrote:
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> The website consists of two parts which are maintained in two
>>>>>>>>> separate
>>>>>>>>>>>>>> respositories:
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> 1) The project website about features, community, etc.
>>>>>>>>>>>>>> 2) The documentation of the project
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> We have the separation because we want to be able to update
>>>>> source
>>>>>>>>> and
>>>>>>>>>>>>>> documentation in one repository to avoid that the documentation
>>>>>>> gets
>>>>>>>>>>> out
>>>>>>>>>>>>> of
>>>>>>>>>>>>>> sync. The documentation is built every night and hosted at
>>>>>>>>>>> ci.apache.org
>>>>>>>>>>>>> to
>>>>>>>>>>>>>> achieve that.
>>>>>>>>>>>>>>
>>>>>>>>>>>>>> IMO, this separation makes sense, because the project website
>>>>> is
>>>>>>> not
>>>>>>>>>>>>>> changed very often whereas the documentation should be touched
>>>>>>>>> whenever
>>>>>>>>>>>>> the
>>>>>>>>>>>>>> API or behavior is changed. I think it is very important to
>>>>> have
>>>>>>>>>>>>>> documentation in sync with the code. In fact, I believe both
>>>>> parts
>>>>>>> of
>>>>>>>>>>> the
>>>>>>>>>>>>>> website should not be related to each other, so they shouldn't
>>>>> be a
>>>>>>>>> way
>>>>>>>>>>>>> to
>>>>>>>>>>>>>> have both parts getting out-of-sync, except for layout / design
>>>>>>> which
>>>>>>>>>>> is
>>>>>>>>>>>>>> nice to have but not crucial. We might even think about
>>>>> changing
>>>>>>> the
>>>>>>>>>>>>>> color-scheme of the documentation to make the difference more
>>>>>>> clear.
>>>>>>>>>>>>>
>>>>>>>>>>>>> Yes, Max pointed this out in the beginning. Let’s change the
>>>>>>>>>>> colors/design
>>>>>>>>>>>>> to make the distinction clear. The confusion comes from the fact
>>>>>>> that
>>>>>>>>>>> they
>>>>>>>>>>>>> look similar. It only makes sense to assume that they are
>>>>> hosted on
>>>>>>>>> the
>>>>>>>>>>>>> same web server etc. But as Fabian said, there are good reasons
>>>>>>>>> against
>>>>>>>>>>> it.
>>>>>>>>>>>>>
>>>>>>>>>>>>> – Ufuk
>>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>>
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>
>>>>
>>>
>>
>