Hi,
I'm right now rewriting the documentation to unify the Java API/Scala API parts with tabs to switch between language (mentioned that before, I know. :D). The problem is now that the doc is very tightly integrated into the website. For example, the sidebar of links is part of the website. (The self contained doc also has the sidebar of links, but if you look closely you will notice it's slightly different.) It is the same for the 0.6 doc and the 0.7 doc, which doesn't work well when those two docs have different pages with differing names. Would it not be easier to make the documentation completely self contained (as it already is) and copy the built files into the website's doc folder. The website would then just have links to the documentation for the separate versions. The problem would then be that the documentation doesn't share the same header as the website anymore. I don't see this as a problem, we could even move the documentation navigation into the header and out of the sidebar. Some people might object though. What do you think? How should we handle this? Cheers, Aljoscha |
Hi Aljoscha,
I think it should not be too difficult to have different menu layouts for the different versions of the website documentation. However, this would make the documentation even more complicated. I'm also unhappy with the current setup of the documentation. The maintenance is quite time-consuming, so I'm happy if you come up with a simpler approach. I agree with having a self contained documentation. This would also allow us to make it part of the release votes and ship it with the binary releases. I think it would be fine to just hardcode a link to flink.incubator.apache.org into the standalone documentation. Robert On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek <[hidden email]> wrote: > Hi, > I'm right now rewriting the documentation to unify the Java API/Scala > API parts with tabs to switch between language (mentioned that before, > I know. :D). > > The problem is now that the doc is very tightly integrated into the > website. For example, the sidebar of links is part of the website. > (The self contained doc also has the sidebar of links, but if you look > closely you will notice it's slightly different.) It is the same for > the 0.6 doc and the 0.7 doc, which doesn't work well when those two > docs have different pages with differing names. > > Would it not be easier to make the documentation completely self > contained (as it already is) and copy the built files into the > website's doc folder. The website would then just have links to the > documentation for the separate versions. > > The problem would then be that the documentation doesn't share the > same header as the website anymore. I don't see this as a problem, we > could even move the documentation navigation into the header and out > of the sidebar. Some people might object though. > > What do you think? How should we handle this? > > Cheers, > Aljoscha > |
> However, this would make the documentation even more complicated.
Exactly, that's what I'm trying to avoid. If nobody has anything against it I will try to make the documentation self contained, move navigation to the top bar, and generally make things less cumbersome. :D On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger <[hidden email]> wrote: > Hi Aljoscha, > > I think it should not be too difficult to have different menu layouts for > the different versions of the website documentation. However, this would > make the documentation even more complicated. > > I'm also unhappy with the current setup of the documentation. The > maintenance is quite time-consuming, so I'm happy if you come up with a > simpler approach. > > I agree with having a self contained documentation. This would also allow > us to make it part of the release votes and ship it with the binary > releases. > > > I think it would be fine to just hardcode a link to > flink.incubator.apache.org into the standalone documentation. > > > Robert > > > > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek <[hidden email]> > wrote: > >> Hi, >> I'm right now rewriting the documentation to unify the Java API/Scala >> API parts with tabs to switch between language (mentioned that before, >> I know. :D). >> >> The problem is now that the doc is very tightly integrated into the >> website. For example, the sidebar of links is part of the website. >> (The self contained doc also has the sidebar of links, but if you look >> closely you will notice it's slightly different.) It is the same for >> the 0.6 doc and the 0.7 doc, which doesn't work well when those two >> docs have different pages with differing names. >> >> Would it not be easier to make the documentation completely self >> contained (as it already is) and copy the built files into the >> website's doc folder. The website would then just have links to the >> documentation for the separate versions. >> >> The problem would then be that the documentation doesn't share the >> same header as the website anymore. I don't see this as a problem, we >> could even move the documentation navigation into the header and out >> of the sidebar. Some people might object though. >> >> What do you think? How should we handle this? >> >> Cheers, >> Aljoscha >> |
+1
I think a standalone docs site with a different nav bar will be more usable. On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek <[hidden email]> wrote: > > However, this would make the documentation even more complicated. > > Exactly, that's what I'm trying to avoid. > > If nobody has anything against it I will try to make the documentation > self contained, move navigation to the top bar, and generally make > things less cumbersome. :D > > On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger <[hidden email]> > wrote: > > Hi Aljoscha, > > > > I think it should not be too difficult to have different menu layouts for > > the different versions of the website documentation. However, this would > > make the documentation even more complicated. > > > > I'm also unhappy with the current setup of the documentation. The > > maintenance is quite time-consuming, so I'm happy if you come up with a > > simpler approach. > > > > I agree with having a self contained documentation. This would also allow > > us to make it part of the release votes and ship it with the binary > > releases. > > > > > > I think it would be fine to just hardcode a link to > > flink.incubator.apache.org into the standalone documentation. > > > > > > Robert > > > > > > > > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek <[hidden email]> > > wrote: > > > >> Hi, > >> I'm right now rewriting the documentation to unify the Java API/Scala > >> API parts with tabs to switch between language (mentioned that before, > >> I know. :D). > >> > >> The problem is now that the doc is very tightly integrated into the > >> website. For example, the sidebar of links is part of the website. > >> (The self contained doc also has the sidebar of links, but if you look > >> closely you will notice it's slightly different.) It is the same for > >> the 0.6 doc and the 0.7 doc, which doesn't work well when those two > >> docs have different pages with differing names. > >> > >> Would it not be easier to make the documentation completely self > >> contained (as it already is) and copy the built files into the > >> website's doc folder. The website would then just have links to the > >> documentation for the separate versions. > >> > >> The problem would then be that the documentation doesn't share the > >> same header as the website anymore. I don't see this as a problem, we > >> could even move the documentation navigation into the header and out > >> of the sidebar. Some people might object though. > >> > >> What do you think? How should we handle this? > >> > >> Cheers, > >> Aljoscha > >> > |
I updated the Documentation, now I need some eyeballs to look this
thing over so could you please have a look and tell me what you think. :D I added and overview page, the programming guide and the examples are now unified. I also did some little touchups here and there. To build it just checkout my scala-rework branch and run the docs build script: https://github.com/aljoscha/incubator-flink/tree/scala-rework cd docs ./build_docs.sh -p On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas <[hidden email]> wrote: > +1 > > I think a standalone docs site with a different nav bar will be more > usable. > > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek <[hidden email]> > wrote: > >> > However, this would make the documentation even more complicated. >> >> Exactly, that's what I'm trying to avoid. >> >> If nobody has anything against it I will try to make the documentation >> self contained, move navigation to the top bar, and generally make >> things less cumbersome. :D >> >> On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger <[hidden email]> >> wrote: >> > Hi Aljoscha, >> > >> > I think it should not be too difficult to have different menu layouts for >> > the different versions of the website documentation. However, this would >> > make the documentation even more complicated. >> > >> > I'm also unhappy with the current setup of the documentation. The >> > maintenance is quite time-consuming, so I'm happy if you come up with a >> > simpler approach. >> > >> > I agree with having a self contained documentation. This would also allow >> > us to make it part of the release votes and ship it with the binary >> > releases. >> > >> > >> > I think it would be fine to just hardcode a link to >> > flink.incubator.apache.org into the standalone documentation. >> > >> > >> > Robert >> > >> > >> > >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek <[hidden email]> >> > wrote: >> > >> >> Hi, >> >> I'm right now rewriting the documentation to unify the Java API/Scala >> >> API parts with tabs to switch between language (mentioned that before, >> >> I know. :D). >> >> >> >> The problem is now that the doc is very tightly integrated into the >> >> website. For example, the sidebar of links is part of the website. >> >> (The self contained doc also has the sidebar of links, but if you look >> >> closely you will notice it's slightly different.) It is the same for >> >> the 0.6 doc and the 0.7 doc, which doesn't work well when those two >> >> docs have different pages with differing names. >> >> >> >> Would it not be easier to make the documentation completely self >> >> contained (as it already is) and copy the built files into the >> >> website's doc folder. The website would then just have links to the >> >> documentation for the separate versions. >> >> >> >> The problem would then be that the documentation doesn't share the >> >> same header as the website anymore. I don't see this as a problem, we >> >> could even move the documentation navigation into the header and out >> >> of the sidebar. Some people might object though. >> >> >> >> What do you think? How should we handle this? >> >> >> >> Cheers, >> >> Aljoscha >> >> >> |
I like it very much, but a) there are some typos and minor issues, and b)
it looks very much like [1] (I'm pointing this out without any judgement). Regaring a) Should we post issues here or do a PR against your repo? - I don't like the top link "Doc"... let's just called it what it is: "Overview". - And maybe let's put more attention on the link "Flink Programming Guide" under "Programming Guides" somehow, because this is the "main" programming guide. [1] https://spark.apache.org/docs/latest/ On Fri, Sep 19, 2014 at 3:12 PM, Aljoscha Krettek <[hidden email]> wrote: > I updated the Documentation, now I need some eyeballs to look this > thing over so could you please have a look and tell me what you think. > :D > > I added and overview page, the programming guide and the examples are > now unified. I also did some little touchups here and there. > > To build it just checkout my scala-rework branch and run the docs build > script: > https://github.com/aljoscha/incubator-flink/tree/scala-rework > > cd docs > ./build_docs.sh -p > > On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas <[hidden email]> > wrote: > > +1 > > > > I think a standalone docs site with a different nav bar will be more > > usable. > > > > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek <[hidden email]> > > wrote: > > > >> > However, this would make the documentation even more complicated. > >> > >> Exactly, that's what I'm trying to avoid. > >> > >> If nobody has anything against it I will try to make the documentation > >> self contained, move navigation to the top bar, and generally make > >> things less cumbersome. :D > >> > >> On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger <[hidden email]> > >> wrote: > >> > Hi Aljoscha, > >> > > >> > I think it should not be too difficult to have different menu layouts > for > >> > the different versions of the website documentation. However, this > would > >> > make the documentation even more complicated. > >> > > >> > I'm also unhappy with the current setup of the documentation. The > >> > maintenance is quite time-consuming, so I'm happy if you come up with > a > >> > simpler approach. > >> > > >> > I agree with having a self contained documentation. This would also > allow > >> > us to make it part of the release votes and ship it with the binary > >> > releases. > >> > > >> > > >> > I think it would be fine to just hardcode a link to > >> > flink.incubator.apache.org into the standalone documentation. > >> > > >> > > >> > Robert > >> > > >> > > >> > > >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek < > [hidden email]> > >> > wrote: > >> > > >> >> Hi, > >> >> I'm right now rewriting the documentation to unify the Java API/Scala > >> >> API parts with tabs to switch between language (mentioned that > before, > >> >> I know. :D). > >> >> > >> >> The problem is now that the doc is very tightly integrated into the > >> >> website. For example, the sidebar of links is part of the website. > >> >> (The self contained doc also has the sidebar of links, but if you > look > >> >> closely you will notice it's slightly different.) It is the same for > >> >> the 0.6 doc and the 0.7 doc, which doesn't work well when those two > >> >> docs have different pages with differing names. > >> >> > >> >> Would it not be easier to make the documentation completely self > >> >> contained (as it already is) and copy the built files into the > >> >> website's doc folder. The website would then just have links to the > >> >> documentation for the separate versions. > >> >> > >> >> The problem would then be that the documentation doesn't share the > >> >> same header as the website anymore. I don't see this as a problem, we > >> >> could even move the documentation navigation into the header and out > >> >> of the sidebar. Some people might object though. > >> >> > >> >> What do you think? How should we handle this? > >> >> > >> >> Cheers, > >> >> Aljoscha > >> >> > >> > |
Yes, I know, their documentation structure is quite good and I'm
obviously inspired by it. :D Does anyone think this could become a problem? The problem with "Overview" is that it is not clear whether it's an overview of the documentation or Apache Flink in general. But ok, let's go with Overview if no-one objects. I mention the Programming Guide in the first Paragraph but If you come up with something better feel free to add it. I think doing PRs agains my repo should be easiest. @robert: I'm now also generating the javadoc via jekyll, it's in _plugins/copy_api_dirs.rb On Fri, Sep 19, 2014 at 3:27 PM, Ufuk Celebi <[hidden email]> wrote: > I like it very much, but a) there are some typos and minor issues, and b) > it looks very much like [1] (I'm pointing this out without any judgement). > > Regaring a) Should we post issues here or do a PR against your repo? > > - I don't like the top link "Doc"... let's just called it what it is: > "Overview". > - And maybe let's put more attention on the link "Flink Programming Guide" > under "Programming Guides" somehow, because this is the "main" programming > guide. > > [1] https://spark.apache.org/docs/latest/ > > On Fri, Sep 19, 2014 at 3:12 PM, Aljoscha Krettek <[hidden email]> > wrote: > >> I updated the Documentation, now I need some eyeballs to look this >> thing over so could you please have a look and tell me what you think. >> :D >> >> I added and overview page, the programming guide and the examples are >> now unified. I also did some little touchups here and there. >> >> To build it just checkout my scala-rework branch and run the docs build >> script: >> https://github.com/aljoscha/incubator-flink/tree/scala-rework >> >> cd docs >> ./build_docs.sh -p >> >> On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas <[hidden email]> >> wrote: >> > +1 >> > >> > I think a standalone docs site with a different nav bar will be more >> > usable. >> > >> > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek <[hidden email]> >> > wrote: >> > >> >> > However, this would make the documentation even more complicated. >> >> >> >> Exactly, that's what I'm trying to avoid. >> >> >> >> If nobody has anything against it I will try to make the documentation >> >> self contained, move navigation to the top bar, and generally make >> >> things less cumbersome. :D >> >> >> >> On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger <[hidden email]> >> >> wrote: >> >> > Hi Aljoscha, >> >> > >> >> > I think it should not be too difficult to have different menu layouts >> for >> >> > the different versions of the website documentation. However, this >> would >> >> > make the documentation even more complicated. >> >> > >> >> > I'm also unhappy with the current setup of the documentation. The >> >> > maintenance is quite time-consuming, so I'm happy if you come up with >> a >> >> > simpler approach. >> >> > >> >> > I agree with having a self contained documentation. This would also >> allow >> >> > us to make it part of the release votes and ship it with the binary >> >> > releases. >> >> > >> >> > >> >> > I think it would be fine to just hardcode a link to >> >> > flink.incubator.apache.org into the standalone documentation. >> >> > >> >> > >> >> > Robert >> >> > >> >> > >> >> > >> >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek < >> [hidden email]> >> >> > wrote: >> >> > >> >> >> Hi, >> >> >> I'm right now rewriting the documentation to unify the Java API/Scala >> >> >> API parts with tabs to switch between language (mentioned that >> before, >> >> >> I know. :D). >> >> >> >> >> >> The problem is now that the doc is very tightly integrated into the >> >> >> website. For example, the sidebar of links is part of the website. >> >> >> (The self contained doc also has the sidebar of links, but if you >> look >> >> >> closely you will notice it's slightly different.) It is the same for >> >> >> the 0.6 doc and the 0.7 doc, which doesn't work well when those two >> >> >> docs have different pages with differing names. >> >> >> >> >> >> Would it not be easier to make the documentation completely self >> >> >> contained (as it already is) and copy the built files into the >> >> >> website's doc folder. The website would then just have links to the >> >> >> documentation for the separate versions. >> >> >> >> >> >> The problem would then be that the documentation doesn't share the >> >> >> same header as the website anymore. I don't see this as a problem, we >> >> >> could even move the documentation navigation into the header and out >> >> >> of the sidebar. Some people might object though. >> >> >> >> >> >> What do you think? How should we handle this? >> >> >> >> >> >> Cheers, >> >> >> Aljoscha >> >> >> >> >> >> |
I like the new look as well. You could call it "Contents"
Kostas On Fri, Sep 19, 2014 at 3:40 PM, Aljoscha Krettek <[hidden email]> wrote: > Yes, I know, their documentation structure is quite good and I'm > obviously inspired by it. :D Does anyone think this could become a > problem? > > The problem with "Overview" is that it is not clear whether it's an > overview of the documentation or Apache Flink in general. But ok, > let's go with Overview if no-one objects. > > I mention the Programming Guide in the first Paragraph but If you come > up with something better feel free to add it. > > I think doing PRs agains my repo should be easiest. > > @robert: I'm now also generating the javadoc via jekyll, it's in > _plugins/copy_api_dirs.rb > > On Fri, Sep 19, 2014 at 3:27 PM, Ufuk Celebi <[hidden email]> wrote: > > I like it very much, but a) there are some typos and minor issues, and b) > > it looks very much like [1] (I'm pointing this out without any > judgement). > > > > Regaring a) Should we post issues here or do a PR against your repo? > > > > - I don't like the top link "Doc"... let's just called it what it is: > > "Overview". > > - And maybe let's put more attention on the link "Flink Programming > Guide" > > under "Programming Guides" somehow, because this is the "main" > programming > > guide. > > > > [1] https://spark.apache.org/docs/latest/ > > > > On Fri, Sep 19, 2014 at 3:12 PM, Aljoscha Krettek <[hidden email]> > > wrote: > > > >> I updated the Documentation, now I need some eyeballs to look this > >> thing over so could you please have a look and tell me what you think. > >> :D > >> > >> I added and overview page, the programming guide and the examples are > >> now unified. I also did some little touchups here and there. > >> > >> To build it just checkout my scala-rework branch and run the docs build > >> script: > >> https://github.com/aljoscha/incubator-flink/tree/scala-rework > >> > >> cd docs > >> ./build_docs.sh -p > >> > >> On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas <[hidden email]> > >> wrote: > >> > +1 > >> > > >> > I think a standalone docs site with a different nav bar will be more > >> > usable. > >> > > >> > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek < > [hidden email]> > >> > wrote: > >> > > >> >> > However, this would make the documentation even more complicated. > >> >> > >> >> Exactly, that's what I'm trying to avoid. > >> >> > >> >> If nobody has anything against it I will try to make the > documentation > >> >> self contained, move navigation to the top bar, and generally make > >> >> things less cumbersome. :D > >> >> > >> >> On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger < > [hidden email]> > >> >> wrote: > >> >> > Hi Aljoscha, > >> >> > > >> >> > I think it should not be too difficult to have different menu > layouts > >> for > >> >> > the different versions of the website documentation. However, this > >> would > >> >> > make the documentation even more complicated. > >> >> > > >> >> > I'm also unhappy with the current setup of the documentation. The > >> >> > maintenance is quite time-consuming, so I'm happy if you come up > with > >> a > >> >> > simpler approach. > >> >> > > >> >> > I agree with having a self contained documentation. This would also > >> allow > >> >> > us to make it part of the release votes and ship it with the binary > >> >> > releases. > >> >> > > >> >> > > >> >> > I think it would be fine to just hardcode a link to > >> >> > flink.incubator.apache.org into the standalone documentation. > >> >> > > >> >> > > >> >> > Robert > >> >> > > >> >> > > >> >> > > >> >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek < > >> [hidden email]> > >> >> > wrote: > >> >> > > >> >> >> Hi, > >> >> >> I'm right now rewriting the documentation to unify the Java > API/Scala > >> >> >> API parts with tabs to switch between language (mentioned that > >> before, > >> >> >> I know. :D). > >> >> >> > >> >> >> The problem is now that the doc is very tightly integrated into > the > >> >> >> website. For example, the sidebar of links is part of the website. > >> >> >> (The self contained doc also has the sidebar of links, but if you > >> look > >> >> >> closely you will notice it's slightly different.) It is the same > for > >> >> >> the 0.6 doc and the 0.7 doc, which doesn't work well when those > two > >> >> >> docs have different pages with differing names. > >> >> >> > >> >> >> Would it not be easier to make the documentation completely self > >> >> >> contained (as it already is) and copy the built files into the > >> >> >> website's doc folder. The website would then just have links to > the > >> >> >> documentation for the separate versions. > >> >> >> > >> >> >> The problem would then be that the documentation doesn't share the > >> >> >> same header as the website anymore. I don't see this as a > problem, we > >> >> >> could even move the documentation navigation into the header and > out > >> >> >> of the sidebar. Some people might object though. > >> >> >> > >> >> >> What do you think? How should we handle this? > >> >> >> > >> >> >> Cheers, > >> >> >> Aljoscha > >> >> >> > >> >> > >> > |
About the "Java API Transformations" Page. Why do we have it? The
operations are described in the Javadoc for DataSet and Grouping. Having it duplicated here just means that we always have to keep it in sync. We could just have a link to the Javadoc in the Programming Guide in addition to the operations overview. What do you think? On Fri, Sep 19, 2014 at 3:48 PM, Kostas Tzoumas <[hidden email]> wrote: > I like the new look as well. You could call it "Contents" > > Kostas > > On Fri, Sep 19, 2014 at 3:40 PM, Aljoscha Krettek <[hidden email]> > wrote: > >> Yes, I know, their documentation structure is quite good and I'm >> obviously inspired by it. :D Does anyone think this could become a >> problem? >> >> The problem with "Overview" is that it is not clear whether it's an >> overview of the documentation or Apache Flink in general. But ok, >> let's go with Overview if no-one objects. >> >> I mention the Programming Guide in the first Paragraph but If you come >> up with something better feel free to add it. >> >> I think doing PRs agains my repo should be easiest. >> >> @robert: I'm now also generating the javadoc via jekyll, it's in >> _plugins/copy_api_dirs.rb >> >> On Fri, Sep 19, 2014 at 3:27 PM, Ufuk Celebi <[hidden email]> wrote: >> > I like it very much, but a) there are some typos and minor issues, and b) >> > it looks very much like [1] (I'm pointing this out without any >> judgement). >> > >> > Regaring a) Should we post issues here or do a PR against your repo? >> > >> > - I don't like the top link "Doc"... let's just called it what it is: >> > "Overview". >> > - And maybe let's put more attention on the link "Flink Programming >> Guide" >> > under "Programming Guides" somehow, because this is the "main" >> programming >> > guide. >> > >> > [1] https://spark.apache.org/docs/latest/ >> > >> > On Fri, Sep 19, 2014 at 3:12 PM, Aljoscha Krettek <[hidden email]> >> > wrote: >> > >> >> I updated the Documentation, now I need some eyeballs to look this >> >> thing over so could you please have a look and tell me what you think. >> >> :D >> >> >> >> I added and overview page, the programming guide and the examples are >> >> now unified. I also did some little touchups here and there. >> >> >> >> To build it just checkout my scala-rework branch and run the docs build >> >> script: >> >> https://github.com/aljoscha/incubator-flink/tree/scala-rework >> >> >> >> cd docs >> >> ./build_docs.sh -p >> >> >> >> On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas <[hidden email]> >> >> wrote: >> >> > +1 >> >> > >> >> > I think a standalone docs site with a different nav bar will be more >> >> > usable. >> >> > >> >> > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek < >> [hidden email]> >> >> > wrote: >> >> > >> >> >> > However, this would make the documentation even more complicated. >> >> >> >> >> >> Exactly, that's what I'm trying to avoid. >> >> >> >> >> >> If nobody has anything against it I will try to make the >> documentation >> >> >> self contained, move navigation to the top bar, and generally make >> >> >> things less cumbersome. :D >> >> >> >> >> >> On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger < >> [hidden email]> >> >> >> wrote: >> >> >> > Hi Aljoscha, >> >> >> > >> >> >> > I think it should not be too difficult to have different menu >> layouts >> >> for >> >> >> > the different versions of the website documentation. However, this >> >> would >> >> >> > make the documentation even more complicated. >> >> >> > >> >> >> > I'm also unhappy with the current setup of the documentation. The >> >> >> > maintenance is quite time-consuming, so I'm happy if you come up >> with >> >> a >> >> >> > simpler approach. >> >> >> > >> >> >> > I agree with having a self contained documentation. This would also >> >> allow >> >> >> > us to make it part of the release votes and ship it with the binary >> >> >> > releases. >> >> >> > >> >> >> > >> >> >> > I think it would be fine to just hardcode a link to >> >> >> > flink.incubator.apache.org into the standalone documentation. >> >> >> > >> >> >> > >> >> >> > Robert >> >> >> > >> >> >> > >> >> >> > >> >> >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek < >> >> [hidden email]> >> >> >> > wrote: >> >> >> > >> >> >> >> Hi, >> >> >> >> I'm right now rewriting the documentation to unify the Java >> API/Scala >> >> >> >> API parts with tabs to switch between language (mentioned that >> >> before, >> >> >> >> I know. :D). >> >> >> >> >> >> >> >> The problem is now that the doc is very tightly integrated into >> the >> >> >> >> website. For example, the sidebar of links is part of the website. >> >> >> >> (The self contained doc also has the sidebar of links, but if you >> >> look >> >> >> >> closely you will notice it's slightly different.) It is the same >> for >> >> >> >> the 0.6 doc and the 0.7 doc, which doesn't work well when those >> two >> >> >> >> docs have different pages with differing names. >> >> >> >> >> >> >> >> Would it not be easier to make the documentation completely self >> >> >> >> contained (as it already is) and copy the built files into the >> >> >> >> website's doc folder. The website would then just have links to >> the >> >> >> >> documentation for the separate versions. >> >> >> >> >> >> >> >> The problem would then be that the documentation doesn't share the >> >> >> >> same header as the website anymore. I don't see this as a >> problem, we >> >> >> >> could even move the documentation navigation into the header and >> out >> >> >> >> of the sidebar. Some people might object though. >> >> >> >> >> >> >> >> What do you think? How should we handle this? >> >> >> >> >> >> >> >> Cheers, >> >> >> >> Aljoscha >> >> >> >> >> >> >> >> >> >> |
I guess the added value are the examples, which are nice to have for
someone that is learning. On Fri, Sep 19, 2014 at 5:15 PM, Aljoscha Krettek <[hidden email]> wrote: > About the "Java API Transformations" Page. Why do we have it? The > operations are described in the Javadoc for DataSet and Grouping. > Having it duplicated here just means that we always have to keep it in > sync. We could just have a link to the Javadoc in the Programming > Guide in addition to the operations overview. > > What do you think? > > On Fri, Sep 19, 2014 at 3:48 PM, Kostas Tzoumas <[hidden email]> > wrote: > > I like the new look as well. You could call it "Contents" > > > > Kostas > > > > On Fri, Sep 19, 2014 at 3:40 PM, Aljoscha Krettek <[hidden email]> > > wrote: > > > >> Yes, I know, their documentation structure is quite good and I'm > >> obviously inspired by it. :D Does anyone think this could become a > >> problem? > >> > >> The problem with "Overview" is that it is not clear whether it's an > >> overview of the documentation or Apache Flink in general. But ok, > >> let's go with Overview if no-one objects. > >> > >> I mention the Programming Guide in the first Paragraph but If you come > >> up with something better feel free to add it. > >> > >> I think doing PRs agains my repo should be easiest. > >> > >> @robert: I'm now also generating the javadoc via jekyll, it's in > >> _plugins/copy_api_dirs.rb > >> > >> On Fri, Sep 19, 2014 at 3:27 PM, Ufuk Celebi <[hidden email]> wrote: > >> > I like it very much, but a) there are some typos and minor issues, > and b) > >> > it looks very much like [1] (I'm pointing this out without any > >> judgement). > >> > > >> > Regaring a) Should we post issues here or do a PR against your repo? > >> > > >> > - I don't like the top link "Doc"... let's just called it what it is: > >> > "Overview". > >> > - And maybe let's put more attention on the link "Flink Programming > >> Guide" > >> > under "Programming Guides" somehow, because this is the "main" > >> programming > >> > guide. > >> > > >> > [1] https://spark.apache.org/docs/latest/ > >> > > >> > On Fri, Sep 19, 2014 at 3:12 PM, Aljoscha Krettek < > [hidden email]> > >> > wrote: > >> > > >> >> I updated the Documentation, now I need some eyeballs to look this > >> >> thing over so could you please have a look and tell me what you > think. > >> >> :D > >> >> > >> >> I added and overview page, the programming guide and the examples are > >> >> now unified. I also did some little touchups here and there. > >> >> > >> >> To build it just checkout my scala-rework branch and run the docs > build > >> >> script: > >> >> https://github.com/aljoscha/incubator-flink/tree/scala-rework > >> >> > >> >> cd docs > >> >> ./build_docs.sh -p > >> >> > >> >> On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas < > [hidden email]> > >> >> wrote: > >> >> > +1 > >> >> > > >> >> > I think a standalone docs site with a different nav bar will be > more > >> >> > usable. > >> >> > > >> >> > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek < > >> [hidden email]> > >> >> > wrote: > >> >> > > >> >> >> > However, this would make the documentation even more > complicated. > >> >> >> > >> >> >> Exactly, that's what I'm trying to avoid. > >> >> >> > >> >> >> If nobody has anything against it I will try to make the > >> documentation > >> >> >> self contained, move navigation to the top bar, and generally make > >> >> >> things less cumbersome. :D > >> >> >> > >> >> >> On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger < > >> [hidden email]> > >> >> >> wrote: > >> >> >> > Hi Aljoscha, > >> >> >> > > >> >> >> > I think it should not be too difficult to have different menu > >> layouts > >> >> for > >> >> >> > the different versions of the website documentation. However, > this > >> >> would > >> >> >> > make the documentation even more complicated. > >> >> >> > > >> >> >> > I'm also unhappy with the current setup of the documentation. > The > >> >> >> > maintenance is quite time-consuming, so I'm happy if you come up > >> with > >> >> a > >> >> >> > simpler approach. > >> >> >> > > >> >> >> > I agree with having a self contained documentation. This would > also > >> >> allow > >> >> >> > us to make it part of the release votes and ship it with the > binary > >> >> >> > releases. > >> >> >> > > >> >> >> > > >> >> >> > I think it would be fine to just hardcode a link to > >> >> >> > flink.incubator.apache.org into the standalone documentation. > >> >> >> > > >> >> >> > > >> >> >> > Robert > >> >> >> > > >> >> >> > > >> >> >> > > >> >> >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek < > >> >> [hidden email]> > >> >> >> > wrote: > >> >> >> > > >> >> >> >> Hi, > >> >> >> >> I'm right now rewriting the documentation to unify the Java > >> API/Scala > >> >> >> >> API parts with tabs to switch between language (mentioned that > >> >> before, > >> >> >> >> I know. :D). > >> >> >> >> > >> >> >> >> The problem is now that the doc is very tightly integrated into > >> the > >> >> >> >> website. For example, the sidebar of links is part of the > website. > >> >> >> >> (The self contained doc also has the sidebar of links, but if > you > >> >> look > >> >> >> >> closely you will notice it's slightly different.) It is the > same > >> for > >> >> >> >> the 0.6 doc and the 0.7 doc, which doesn't work well when those > >> two > >> >> >> >> docs have different pages with differing names. > >> >> >> >> > >> >> >> >> Would it not be easier to make the documentation completely > self > >> >> >> >> contained (as it already is) and copy the built files into the > >> >> >> >> website's doc folder. The website would then just have links to > >> the > >> >> >> >> documentation for the separate versions. > >> >> >> >> > >> >> >> >> The problem would then be that the documentation doesn't share > the > >> >> >> >> same header as the website anymore. I don't see this as a > >> problem, we > >> >> >> >> could even move the documentation navigation into the header > and > >> out > >> >> >> >> of the sidebar. Some people might object though. > >> >> >> >> > >> >> >> >> What do you think? How should we handle this? > >> >> >> >> > >> >> >> >> Cheers, > >> >> >> >> Aljoscha > >> >> >> >> > >> >> >> > >> >> > >> > |
Mh. I'm actually preferring the old navigation style.
The new navigation requires users to have JavaScript enabled (I know a lot of people who use NoScript). What I also liked about the old layout is that you can see very easily which pages are there. On Fri, Sep 19, 2014 at 5:37 PM, Kostas Tzoumas <[hidden email]> wrote: > I guess the added value are the examples, which are nice to have for > someone that is learning. > > On Fri, Sep 19, 2014 at 5:15 PM, Aljoscha Krettek <[hidden email]> > wrote: > > > About the "Java API Transformations" Page. Why do we have it? The > > operations are described in the Javadoc for DataSet and Grouping. > > Having it duplicated here just means that we always have to keep it in > > sync. We could just have a link to the Javadoc in the Programming > > Guide in addition to the operations overview. > > > > What do you think? > > > > On Fri, Sep 19, 2014 at 3:48 PM, Kostas Tzoumas <[hidden email]> > > wrote: > > > I like the new look as well. You could call it "Contents" > > > > > > Kostas > > > > > > On Fri, Sep 19, 2014 at 3:40 PM, Aljoscha Krettek <[hidden email] > > > > > wrote: > > > > > >> Yes, I know, their documentation structure is quite good and I'm > > >> obviously inspired by it. :D Does anyone think this could become a > > >> problem? > > >> > > >> The problem with "Overview" is that it is not clear whether it's an > > >> overview of the documentation or Apache Flink in general. But ok, > > >> let's go with Overview if no-one objects. > > >> > > >> I mention the Programming Guide in the first Paragraph but If you come > > >> up with something better feel free to add it. > > >> > > >> I think doing PRs agains my repo should be easiest. > > >> > > >> @robert: I'm now also generating the javadoc via jekyll, it's in > > >> _plugins/copy_api_dirs.rb > > >> > > >> On Fri, Sep 19, 2014 at 3:27 PM, Ufuk Celebi <[hidden email]> wrote: > > >> > I like it very much, but a) there are some typos and minor issues, > > and b) > > >> > it looks very much like [1] (I'm pointing this out without any > > >> judgement). > > >> > > > >> > Regaring a) Should we post issues here or do a PR against your repo? > > >> > > > >> > - I don't like the top link "Doc"... let's just called it what it > is: > > >> > "Overview". > > >> > - And maybe let's put more attention on the link "Flink Programming > > >> Guide" > > >> > under "Programming Guides" somehow, because this is the "main" > > >> programming > > >> > guide. > > >> > > > >> > [1] https://spark.apache.org/docs/latest/ > > >> > > > >> > On Fri, Sep 19, 2014 at 3:12 PM, Aljoscha Krettek < > > [hidden email]> > > >> > wrote: > > >> > > > >> >> I updated the Documentation, now I need some eyeballs to look this > > >> >> thing over so could you please have a look and tell me what you > > think. > > >> >> :D > > >> >> > > >> >> I added and overview page, the programming guide and the examples > are > > >> >> now unified. I also did some little touchups here and there. > > >> >> > > >> >> To build it just checkout my scala-rework branch and run the docs > > build > > >> >> script: > > >> >> https://github.com/aljoscha/incubator-flink/tree/scala-rework > > >> >> > > >> >> cd docs > > >> >> ./build_docs.sh -p > > >> >> > > >> >> On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas < > > [hidden email]> > > >> >> wrote: > > >> >> > +1 > > >> >> > > > >> >> > I think a standalone docs site with a different nav bar will be > > more > > >> >> > usable. > > >> >> > > > >> >> > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek < > > >> [hidden email]> > > >> >> > wrote: > > >> >> > > > >> >> >> > However, this would make the documentation even more > > complicated. > > >> >> >> > > >> >> >> Exactly, that's what I'm trying to avoid. > > >> >> >> > > >> >> >> If nobody has anything against it I will try to make the > > >> documentation > > >> >> >> self contained, move navigation to the top bar, and generally > make > > >> >> >> things less cumbersome. :D > > >> >> >> > > >> >> >> On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger < > > >> [hidden email]> > > >> >> >> wrote: > > >> >> >> > Hi Aljoscha, > > >> >> >> > > > >> >> >> > I think it should not be too difficult to have different menu > > >> layouts > > >> >> for > > >> >> >> > the different versions of the website documentation. However, > > this > > >> >> would > > >> >> >> > make the documentation even more complicated. > > >> >> >> > > > >> >> >> > I'm also unhappy with the current setup of the documentation. > > The > > >> >> >> > maintenance is quite time-consuming, so I'm happy if you come > up > > >> with > > >> >> a > > >> >> >> > simpler approach. > > >> >> >> > > > >> >> >> > I agree with having a self contained documentation. This would > > also > > >> >> allow > > >> >> >> > us to make it part of the release votes and ship it with the > > binary > > >> >> >> > releases. > > >> >> >> > > > >> >> >> > > > >> >> >> > I think it would be fine to just hardcode a link to > > >> >> >> > flink.incubator.apache.org into the standalone documentation. > > >> >> >> > > > >> >> >> > > > >> >> >> > Robert > > >> >> >> > > > >> >> >> > > > >> >> >> > > > >> >> >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek < > > >> >> [hidden email]> > > >> >> >> > wrote: > > >> >> >> > > > >> >> >> >> Hi, > > >> >> >> >> I'm right now rewriting the documentation to unify the Java > > >> API/Scala > > >> >> >> >> API parts with tabs to switch between language (mentioned > that > > >> >> before, > > >> >> >> >> I know. :D). > > >> >> >> >> > > >> >> >> >> The problem is now that the doc is very tightly integrated > into > > >> the > > >> >> >> >> website. For example, the sidebar of links is part of the > > website. > > >> >> >> >> (The self contained doc also has the sidebar of links, but if > > you > > >> >> look > > >> >> >> >> closely you will notice it's slightly different.) It is the > > same > > >> for > > >> >> >> >> the 0.6 doc and the 0.7 doc, which doesn't work well when > those > > >> two > > >> >> >> >> docs have different pages with differing names. > > >> >> >> >> > > >> >> >> >> Would it not be easier to make the documentation completely > > self > > >> >> >> >> contained (as it already is) and copy the built files into > the > > >> >> >> >> website's doc folder. The website would then just have links > to > > >> the > > >> >> >> >> documentation for the separate versions. > > >> >> >> >> > > >> >> >> >> The problem would then be that the documentation doesn't > share > > the > > >> >> >> >> same header as the website anymore. I don't see this as a > > >> problem, we > > >> >> >> >> could even move the documentation navigation into the header > > and > > >> out > > >> >> >> >> of the sidebar. Some people might object though. > > >> >> >> >> > > >> >> >> >> What do you think? How should we handle this? > > >> >> >> >> > > >> >> >> >> Cheers, > > >> >> >> >> Aljoscha > > >> >> >> >> > > >> >> >> > > >> >> > > >> > > > |
I updated my branch with some changes. Let me know what you think.
On Fri, Sep 19, 2014 at 5:58 PM, Robert Metzger <[hidden email]> wrote: > Mh. I'm actually preferring the old navigation style. > The new navigation requires users to have JavaScript enabled (I know a lot > of people who use NoScript). > What I also liked about the old layout is that you can see very easily > which pages are there. > > On Fri, Sep 19, 2014 at 5:37 PM, Kostas Tzoumas <[hidden email]> wrote: > >> I guess the added value are the examples, which are nice to have for >> someone that is learning. >> >> On Fri, Sep 19, 2014 at 5:15 PM, Aljoscha Krettek <[hidden email]> >> wrote: >> >> > About the "Java API Transformations" Page. Why do we have it? The >> > operations are described in the Javadoc for DataSet and Grouping. >> > Having it duplicated here just means that we always have to keep it in >> > sync. We could just have a link to the Javadoc in the Programming >> > Guide in addition to the operations overview. >> > >> > What do you think? >> > >> > On Fri, Sep 19, 2014 at 3:48 PM, Kostas Tzoumas <[hidden email]> >> > wrote: >> > > I like the new look as well. You could call it "Contents" >> > > >> > > Kostas >> > > >> > > On Fri, Sep 19, 2014 at 3:40 PM, Aljoscha Krettek <[hidden email] >> > >> > > wrote: >> > > >> > >> Yes, I know, their documentation structure is quite good and I'm >> > >> obviously inspired by it. :D Does anyone think this could become a >> > >> problem? >> > >> >> > >> The problem with "Overview" is that it is not clear whether it's an >> > >> overview of the documentation or Apache Flink in general. But ok, >> > >> let's go with Overview if no-one objects. >> > >> >> > >> I mention the Programming Guide in the first Paragraph but If you come >> > >> up with something better feel free to add it. >> > >> >> > >> I think doing PRs agains my repo should be easiest. >> > >> >> > >> @robert: I'm now also generating the javadoc via jekyll, it's in >> > >> _plugins/copy_api_dirs.rb >> > >> >> > >> On Fri, Sep 19, 2014 at 3:27 PM, Ufuk Celebi <[hidden email]> wrote: >> > >> > I like it very much, but a) there are some typos and minor issues, >> > and b) >> > >> > it looks very much like [1] (I'm pointing this out without any >> > >> judgement). >> > >> > >> > >> > Regaring a) Should we post issues here or do a PR against your repo? >> > >> > >> > >> > - I don't like the top link "Doc"... let's just called it what it >> is: >> > >> > "Overview". >> > >> > - And maybe let's put more attention on the link "Flink Programming >> > >> Guide" >> > >> > under "Programming Guides" somehow, because this is the "main" >> > >> programming >> > >> > guide. >> > >> > >> > >> > [1] https://spark.apache.org/docs/latest/ >> > >> > >> > >> > On Fri, Sep 19, 2014 at 3:12 PM, Aljoscha Krettek < >> > [hidden email]> >> > >> > wrote: >> > >> > >> > >> >> I updated the Documentation, now I need some eyeballs to look this >> > >> >> thing over so could you please have a look and tell me what you >> > think. >> > >> >> :D >> > >> >> >> > >> >> I added and overview page, the programming guide and the examples >> are >> > >> >> now unified. I also did some little touchups here and there. >> > >> >> >> > >> >> To build it just checkout my scala-rework branch and run the docs >> > build >> > >> >> script: >> > >> >> https://github.com/aljoscha/incubator-flink/tree/scala-rework >> > >> >> >> > >> >> cd docs >> > >> >> ./build_docs.sh -p >> > >> >> >> > >> >> On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas < >> > [hidden email]> >> > >> >> wrote: >> > >> >> > +1 >> > >> >> > >> > >> >> > I think a standalone docs site with a different nav bar will be >> > more >> > >> >> > usable. >> > >> >> > >> > >> >> > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek < >> > >> [hidden email]> >> > >> >> > wrote: >> > >> >> > >> > >> >> >> > However, this would make the documentation even more >> > complicated. >> > >> >> >> >> > >> >> >> Exactly, that's what I'm trying to avoid. >> > >> >> >> >> > >> >> >> If nobody has anything against it I will try to make the >> > >> documentation >> > >> >> >> self contained, move navigation to the top bar, and generally >> make >> > >> >> >> things less cumbersome. :D >> > >> >> >> >> > >> >> >> On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger < >> > >> [hidden email]> >> > >> >> >> wrote: >> > >> >> >> > Hi Aljoscha, >> > >> >> >> > >> > >> >> >> > I think it should not be too difficult to have different menu >> > >> layouts >> > >> >> for >> > >> >> >> > the different versions of the website documentation. However, >> > this >> > >> >> would >> > >> >> >> > make the documentation even more complicated. >> > >> >> >> > >> > >> >> >> > I'm also unhappy with the current setup of the documentation. >> > The >> > >> >> >> > maintenance is quite time-consuming, so I'm happy if you come >> up >> > >> with >> > >> >> a >> > >> >> >> > simpler approach. >> > >> >> >> > >> > >> >> >> > I agree with having a self contained documentation. This would >> > also >> > >> >> allow >> > >> >> >> > us to make it part of the release votes and ship it with the >> > binary >> > >> >> >> > releases. >> > >> >> >> > >> > >> >> >> > >> > >> >> >> > I think it would be fine to just hardcode a link to >> > >> >> >> > flink.incubator.apache.org into the standalone documentation. >> > >> >> >> > >> > >> >> >> > >> > >> >> >> > Robert >> > >> >> >> > >> > >> >> >> > >> > >> >> >> > >> > >> >> >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek < >> > >> >> [hidden email]> >> > >> >> >> > wrote: >> > >> >> >> > >> > >> >> >> >> Hi, >> > >> >> >> >> I'm right now rewriting the documentation to unify the Java >> > >> API/Scala >> > >> >> >> >> API parts with tabs to switch between language (mentioned >> that >> > >> >> before, >> > >> >> >> >> I know. :D). >> > >> >> >> >> >> > >> >> >> >> The problem is now that the doc is very tightly integrated >> into >> > >> the >> > >> >> >> >> website. For example, the sidebar of links is part of the >> > website. >> > >> >> >> >> (The self contained doc also has the sidebar of links, but if >> > you >> > >> >> look >> > >> >> >> >> closely you will notice it's slightly different.) It is the >> > same >> > >> for >> > >> >> >> >> the 0.6 doc and the 0.7 doc, which doesn't work well when >> those >> > >> two >> > >> >> >> >> docs have different pages with differing names. >> > >> >> >> >> >> > >> >> >> >> Would it not be easier to make the documentation completely >> > self >> > >> >> >> >> contained (as it already is) and copy the built files into >> the >> > >> >> >> >> website's doc folder. The website would then just have links >> to >> > >> the >> > >> >> >> >> documentation for the separate versions. >> > >> >> >> >> >> > >> >> >> >> The problem would then be that the documentation doesn't >> share >> > the >> > >> >> >> >> same header as the website anymore. I don't see this as a >> > >> problem, we >> > >> >> >> >> could even move the documentation navigation into the header >> > and >> > >> out >> > >> >> >> >> of the sidebar. Some people might object though. >> > >> >> >> >> >> > >> >> >> >> What do you think? How should we handle this? >> > >> >> >> >> >> > >> >> >> >> Cheers, >> > >> >> >> >> Aljoscha >> > >> >> >> >> >> > >> >> >> >> > >> >> >> > >> >> > >> |
@Robert: Did you get genjavadoc to run? The problem I have right now
is that the Java compiler complains because it cannot compile those fake java files generated by genjavadoc. On Fri, Sep 19, 2014 at 6:53 PM, Aljoscha Krettek <[hidden email]> wrote: > I updated my branch with some changes. Let me know what you think. > > On Fri, Sep 19, 2014 at 5:58 PM, Robert Metzger <[hidden email]> wrote: >> Mh. I'm actually preferring the old navigation style. >> The new navigation requires users to have JavaScript enabled (I know a lot >> of people who use NoScript). >> What I also liked about the old layout is that you can see very easily >> which pages are there. >> >> On Fri, Sep 19, 2014 at 5:37 PM, Kostas Tzoumas <[hidden email]> wrote: >> >>> I guess the added value are the examples, which are nice to have for >>> someone that is learning. >>> >>> On Fri, Sep 19, 2014 at 5:15 PM, Aljoscha Krettek <[hidden email]> >>> wrote: >>> >>> > About the "Java API Transformations" Page. Why do we have it? The >>> > operations are described in the Javadoc for DataSet and Grouping. >>> > Having it duplicated here just means that we always have to keep it in >>> > sync. We could just have a link to the Javadoc in the Programming >>> > Guide in addition to the operations overview. >>> > >>> > What do you think? >>> > >>> > On Fri, Sep 19, 2014 at 3:48 PM, Kostas Tzoumas <[hidden email]> >>> > wrote: >>> > > I like the new look as well. You could call it "Contents" >>> > > >>> > > Kostas >>> > > >>> > > On Fri, Sep 19, 2014 at 3:40 PM, Aljoscha Krettek <[hidden email] >>> > >>> > > wrote: >>> > > >>> > >> Yes, I know, their documentation structure is quite good and I'm >>> > >> obviously inspired by it. :D Does anyone think this could become a >>> > >> problem? >>> > >> >>> > >> The problem with "Overview" is that it is not clear whether it's an >>> > >> overview of the documentation or Apache Flink in general. But ok, >>> > >> let's go with Overview if no-one objects. >>> > >> >>> > >> I mention the Programming Guide in the first Paragraph but If you come >>> > >> up with something better feel free to add it. >>> > >> >>> > >> I think doing PRs agains my repo should be easiest. >>> > >> >>> > >> @robert: I'm now also generating the javadoc via jekyll, it's in >>> > >> _plugins/copy_api_dirs.rb >>> > >> >>> > >> On Fri, Sep 19, 2014 at 3:27 PM, Ufuk Celebi <[hidden email]> wrote: >>> > >> > I like it very much, but a) there are some typos and minor issues, >>> > and b) >>> > >> > it looks very much like [1] (I'm pointing this out without any >>> > >> judgement). >>> > >> > >>> > >> > Regaring a) Should we post issues here or do a PR against your repo? >>> > >> > >>> > >> > - I don't like the top link "Doc"... let's just called it what it >>> is: >>> > >> > "Overview". >>> > >> > - And maybe let's put more attention on the link "Flink Programming >>> > >> Guide" >>> > >> > under "Programming Guides" somehow, because this is the "main" >>> > >> programming >>> > >> > guide. >>> > >> > >>> > >> > [1] https://spark.apache.org/docs/latest/ >>> > >> > >>> > >> > On Fri, Sep 19, 2014 at 3:12 PM, Aljoscha Krettek < >>> > [hidden email]> >>> > >> > wrote: >>> > >> > >>> > >> >> I updated the Documentation, now I need some eyeballs to look this >>> > >> >> thing over so could you please have a look and tell me what you >>> > think. >>> > >> >> :D >>> > >> >> >>> > >> >> I added and overview page, the programming guide and the examples >>> are >>> > >> >> now unified. I also did some little touchups here and there. >>> > >> >> >>> > >> >> To build it just checkout my scala-rework branch and run the docs >>> > build >>> > >> >> script: >>> > >> >> https://github.com/aljoscha/incubator-flink/tree/scala-rework >>> > >> >> >>> > >> >> cd docs >>> > >> >> ./build_docs.sh -p >>> > >> >> >>> > >> >> On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas < >>> > [hidden email]> >>> > >> >> wrote: >>> > >> >> > +1 >>> > >> >> > >>> > >> >> > I think a standalone docs site with a different nav bar will be >>> > more >>> > >> >> > usable. >>> > >> >> > >>> > >> >> > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek < >>> > >> [hidden email]> >>> > >> >> > wrote: >>> > >> >> > >>> > >> >> >> > However, this would make the documentation even more >>> > complicated. >>> > >> >> >> >>> > >> >> >> Exactly, that's what I'm trying to avoid. >>> > >> >> >> >>> > >> >> >> If nobody has anything against it I will try to make the >>> > >> documentation >>> > >> >> >> self contained, move navigation to the top bar, and generally >>> make >>> > >> >> >> things less cumbersome. :D >>> > >> >> >> >>> > >> >> >> On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger < >>> > >> [hidden email]> >>> > >> >> >> wrote: >>> > >> >> >> > Hi Aljoscha, >>> > >> >> >> > >>> > >> >> >> > I think it should not be too difficult to have different menu >>> > >> layouts >>> > >> >> for >>> > >> >> >> > the different versions of the website documentation. However, >>> > this >>> > >> >> would >>> > >> >> >> > make the documentation even more complicated. >>> > >> >> >> > >>> > >> >> >> > I'm also unhappy with the current setup of the documentation. >>> > The >>> > >> >> >> > maintenance is quite time-consuming, so I'm happy if you come >>> up >>> > >> with >>> > >> >> a >>> > >> >> >> > simpler approach. >>> > >> >> >> > >>> > >> >> >> > I agree with having a self contained documentation. This would >>> > also >>> > >> >> allow >>> > >> >> >> > us to make it part of the release votes and ship it with the >>> > binary >>> > >> >> >> > releases. >>> > >> >> >> > >>> > >> >> >> > >>> > >> >> >> > I think it would be fine to just hardcode a link to >>> > >> >> >> > flink.incubator.apache.org into the standalone documentation. >>> > >> >> >> > >>> > >> >> >> > >>> > >> >> >> > Robert >>> > >> >> >> > >>> > >> >> >> > >>> > >> >> >> > >>> > >> >> >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek < >>> > >> >> [hidden email]> >>> > >> >> >> > wrote: >>> > >> >> >> > >>> > >> >> >> >> Hi, >>> > >> >> >> >> I'm right now rewriting the documentation to unify the Java >>> > >> API/Scala >>> > >> >> >> >> API parts with tabs to switch between language (mentioned >>> that >>> > >> >> before, >>> > >> >> >> >> I know. :D). >>> > >> >> >> >> >>> > >> >> >> >> The problem is now that the doc is very tightly integrated >>> into >>> > >> the >>> > >> >> >> >> website. For example, the sidebar of links is part of the >>> > website. >>> > >> >> >> >> (The self contained doc also has the sidebar of links, but if >>> > you >>> > >> >> look >>> > >> >> >> >> closely you will notice it's slightly different.) It is the >>> > same >>> > >> for >>> > >> >> >> >> the 0.6 doc and the 0.7 doc, which doesn't work well when >>> those >>> > >> two >>> > >> >> >> >> docs have different pages with differing names. >>> > >> >> >> >> >>> > >> >> >> >> Would it not be easier to make the documentation completely >>> > self >>> > >> >> >> >> contained (as it already is) and copy the built files into >>> the >>> > >> >> >> >> website's doc folder. The website would then just have links >>> to >>> > >> the >>> > >> >> >> >> documentation for the separate versions. >>> > >> >> >> >> >>> > >> >> >> >> The problem would then be that the documentation doesn't >>> share >>> > the >>> > >> >> >> >> same header as the website anymore. I don't see this as a >>> > >> problem, we >>> > >> >> >> >> could even move the documentation navigation into the header >>> > and >>> > >> out >>> > >> >> >> >> of the sidebar. Some people might object though. >>> > >> >> >> >> >>> > >> >> >> >> What do you think? How should we handle this? >>> > >> >> >> >> >>> > >> >> >> >> Cheers, >>> > >> >> >> >> Aljoscha >>> > >> >> >> >> >>> > >> >> >> >>> > >> >> >>> > >> >>> > >>> |
No. I had the same issue.
The generated Java code looked ok (for generated code at least) and I could not really understand why the Java compiler was complaining there. Maybe you should open an issue (https://github.com/typesafehub/genjavadoc) there. On Sat, Sep 20, 2014 at 11:52 AM, Aljoscha Krettek <[hidden email]> wrote: > @Robert: Did you get genjavadoc to run? The problem I have right now > is that the Java compiler complains because it cannot compile those > fake java files generated by genjavadoc. > > On Fri, Sep 19, 2014 at 6:53 PM, Aljoscha Krettek <[hidden email]> > wrote: > > I updated my branch with some changes. Let me know what you think. > > > > On Fri, Sep 19, 2014 at 5:58 PM, Robert Metzger <[hidden email]> > wrote: > >> Mh. I'm actually preferring the old navigation style. > >> The new navigation requires users to have JavaScript enabled (I know a > lot > >> of people who use NoScript). > >> What I also liked about the old layout is that you can see very easily > >> which pages are there. > >> > >> On Fri, Sep 19, 2014 at 5:37 PM, Kostas Tzoumas <[hidden email]> > wrote: > >> > >>> I guess the added value are the examples, which are nice to have for > >>> someone that is learning. > >>> > >>> On Fri, Sep 19, 2014 at 5:15 PM, Aljoscha Krettek <[hidden email] > > > >>> wrote: > >>> > >>> > About the "Java API Transformations" Page. Why do we have it? The > >>> > operations are described in the Javadoc for DataSet and Grouping. > >>> > Having it duplicated here just means that we always have to keep it > in > >>> > sync. We could just have a link to the Javadoc in the Programming > >>> > Guide in addition to the operations overview. > >>> > > >>> > What do you think? > >>> > > >>> > On Fri, Sep 19, 2014 at 3:48 PM, Kostas Tzoumas <[hidden email] > > > >>> > wrote: > >>> > > I like the new look as well. You could call it "Contents" > >>> > > > >>> > > Kostas > >>> > > > >>> > > On Fri, Sep 19, 2014 at 3:40 PM, Aljoscha Krettek < > [hidden email] > >>> > > >>> > > wrote: > >>> > > > >>> > >> Yes, I know, their documentation structure is quite good and I'm > >>> > >> obviously inspired by it. :D Does anyone think this could become a > >>> > >> problem? > >>> > >> > >>> > >> The problem with "Overview" is that it is not clear whether it's > an > >>> > >> overview of the documentation or Apache Flink in general. But ok, > >>> > >> let's go with Overview if no-one objects. > >>> > >> > >>> > >> I mention the Programming Guide in the first Paragraph but If you > come > >>> > >> up with something better feel free to add it. > >>> > >> > >>> > >> I think doing PRs agains my repo should be easiest. > >>> > >> > >>> > >> @robert: I'm now also generating the javadoc via jekyll, it's in > >>> > >> _plugins/copy_api_dirs.rb > >>> > >> > >>> > >> On Fri, Sep 19, 2014 at 3:27 PM, Ufuk Celebi <[hidden email]> > wrote: > >>> > >> > I like it very much, but a) there are some typos and minor > issues, > >>> > and b) > >>> > >> > it looks very much like [1] (I'm pointing this out without any > >>> > >> judgement). > >>> > >> > > >>> > >> > Regaring a) Should we post issues here or do a PR against your > repo? > >>> > >> > > >>> > >> > - I don't like the top link "Doc"... let's just called it what > it > >>> is: > >>> > >> > "Overview". > >>> > >> > - And maybe let's put more attention on the link "Flink > Programming > >>> > >> Guide" > >>> > >> > under "Programming Guides" somehow, because this is the "main" > >>> > >> programming > >>> > >> > guide. > >>> > >> > > >>> > >> > [1] https://spark.apache.org/docs/latest/ > >>> > >> > > >>> > >> > On Fri, Sep 19, 2014 at 3:12 PM, Aljoscha Krettek < > >>> > [hidden email]> > >>> > >> > wrote: > >>> > >> > > >>> > >> >> I updated the Documentation, now I need some eyeballs to look > this > >>> > >> >> thing over so could you please have a look and tell me what you > >>> > think. > >>> > >> >> :D > >>> > >> >> > >>> > >> >> I added and overview page, the programming guide and the > examples > >>> are > >>> > >> >> now unified. I also did some little touchups here and there. > >>> > >> >> > >>> > >> >> To build it just checkout my scala-rework branch and run the > docs > >>> > build > >>> > >> >> script: > >>> > >> >> https://github.com/aljoscha/incubator-flink/tree/scala-rework > >>> > >> >> > >>> > >> >> cd docs > >>> > >> >> ./build_docs.sh -p > >>> > >> >> > >>> > >> >> On Fri, Sep 19, 2014 at 11:50 AM, Kostas Tzoumas < > >>> > [hidden email]> > >>> > >> >> wrote: > >>> > >> >> > +1 > >>> > >> >> > > >>> > >> >> > I think a standalone docs site with a different nav bar will > be > >>> > more > >>> > >> >> > usable. > >>> > >> >> > > >>> > >> >> > On Fri, Sep 19, 2014 at 11:03 AM, Aljoscha Krettek < > >>> > >> [hidden email]> > >>> > >> >> > wrote: > >>> > >> >> > > >>> > >> >> >> > However, this would make the documentation even more > >>> > complicated. > >>> > >> >> >> > >>> > >> >> >> Exactly, that's what I'm trying to avoid. > >>> > >> >> >> > >>> > >> >> >> If nobody has anything against it I will try to make the > >>> > >> documentation > >>> > >> >> >> self contained, move navigation to the top bar, and > generally > >>> make > >>> > >> >> >> things less cumbersome. :D > >>> > >> >> >> > >>> > >> >> >> On Fri, Sep 19, 2014 at 10:35 AM, Robert Metzger < > >>> > >> [hidden email]> > >>> > >> >> >> wrote: > >>> > >> >> >> > Hi Aljoscha, > >>> > >> >> >> > > >>> > >> >> >> > I think it should not be too difficult to have different > menu > >>> > >> layouts > >>> > >> >> for > >>> > >> >> >> > the different versions of the website documentation. > However, > >>> > this > >>> > >> >> would > >>> > >> >> >> > make the documentation even more complicated. > >>> > >> >> >> > > >>> > >> >> >> > I'm also unhappy with the current setup of the > documentation. > >>> > The > >>> > >> >> >> > maintenance is quite time-consuming, so I'm happy if you > come > >>> up > >>> > >> with > >>> > >> >> a > >>> > >> >> >> > simpler approach. > >>> > >> >> >> > > >>> > >> >> >> > I agree with having a self contained documentation. This > would > >>> > also > >>> > >> >> allow > >>> > >> >> >> > us to make it part of the release votes and ship it with > the > >>> > binary > >>> > >> >> >> > releases. > >>> > >> >> >> > > >>> > >> >> >> > > >>> > >> >> >> > I think it would be fine to just hardcode a link to > >>> > >> >> >> > flink.incubator.apache.org into the standalone > documentation. > >>> > >> >> >> > > >>> > >> >> >> > > >>> > >> >> >> > Robert > >>> > >> >> >> > > >>> > >> >> >> > > >>> > >> >> >> > > >>> > >> >> >> > On Fri, Sep 19, 2014 at 9:45 AM, Aljoscha Krettek < > >>> > >> >> [hidden email]> > >>> > >> >> >> > wrote: > >>> > >> >> >> > > >>> > >> >> >> >> Hi, > >>> > >> >> >> >> I'm right now rewriting the documentation to unify the > Java > >>> > >> API/Scala > >>> > >> >> >> >> API parts with tabs to switch between language (mentioned > >>> that > >>> > >> >> before, > >>> > >> >> >> >> I know. :D). > >>> > >> >> >> >> > >>> > >> >> >> >> The problem is now that the doc is very tightly > integrated > >>> into > >>> > >> the > >>> > >> >> >> >> website. For example, the sidebar of links is part of the > >>> > website. > >>> > >> >> >> >> (The self contained doc also has the sidebar of links, > but if > >>> > you > >>> > >> >> look > >>> > >> >> >> >> closely you will notice it's slightly different.) It is > the > >>> > same > >>> > >> for > >>> > >> >> >> >> the 0.6 doc and the 0.7 doc, which doesn't work well when > >>> those > >>> > >> two > >>> > >> >> >> >> docs have different pages with differing names. > >>> > >> >> >> >> > >>> > >> >> >> >> Would it not be easier to make the documentation > completely > >>> > self > >>> > >> >> >> >> contained (as it already is) and copy the built files > into > >>> the > >>> > >> >> >> >> website's doc folder. The website would then just have > links > >>> to > >>> > >> the > >>> > >> >> >> >> documentation for the separate versions. > >>> > >> >> >> >> > >>> > >> >> >> >> The problem would then be that the documentation doesn't > >>> share > >>> > the > >>> > >> >> >> >> same header as the website anymore. I don't see this as a > >>> > >> problem, we > >>> > >> >> >> >> could even move the documentation navigation into the > header > >>> > and > >>> > >> out > >>> > >> >> >> >> of the sidebar. Some people might object though. > >>> > >> >> >> >> > >>> > >> >> >> >> What do you think? How should we handle this? > >>> > >> >> >> >> > >>> > >> >> >> >> Cheers, > >>> > >> >> >> >> Aljoscha > >>> > >> >> >> >> > >>> > >> >> >> > >>> > >> >> > >>> > >> > >>> > > >>> > |
Free forum by Nabble | Edit this page |