I like the new look as well. You could call it "Contents" Kostas
On Fri, Sep 19, 2014 at 3:40 PM, Aljoscha Krettek <[email protected]> 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 <[email protected]> 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 <[email protected]> > > 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 <[email protected]> > >> 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 < > [email protected]> > >> > 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 < > [email protected]> > >> >> 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 < > >> [email protected]> > >> >> > 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 > >> >> >> > >> >> > >> >
