Return-Path: X-Original-To: apmail-flink-dev-archive@www.apache.org Delivered-To: apmail-flink-dev-archive@www.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 0393411DD6 for ; Fri, 19 Sep 2014 15:15:46 +0000 (UTC) Received: (qmail 3240 invoked by uid 500); 19 Sep 2014 15:15:45 -0000 Delivered-To: apmail-flink-dev-archive@flink.apache.org Received: (qmail 3183 invoked by uid 500); 19 Sep 2014 15:15:45 -0000 Mailing-List: contact dev-help@flink.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@flink.incubator.apache.org Delivered-To: mailing list dev@flink.incubator.apache.org Received: (qmail 3172 invoked by uid 99); 19 Sep 2014 15:15:45 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 19 Sep 2014 15:15:45 +0000 X-ASF-Spam-Status: No, hits=-2000.7 required=5.0 tests=ALL_TRUSTED,RP_MATCHES_RCVD X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO mail.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with SMTP; Fri, 19 Sep 2014 15:15:23 +0000 Received: (qmail 2884 invoked by uid 99); 19 Sep 2014 15:15:20 -0000 Received: from minotaur.apache.org (HELO minotaur.apache.org) (140.211.11.9) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 19 Sep 2014 15:15:20 +0000 Received: from localhost (HELO mail-vc0-f181.google.com) (127.0.0.1) (smtp-auth username aljoscha, mechanism plain) by minotaur.apache.org (qpsmtpd/0.29) with ESMTP; Fri, 19 Sep 2014 15:15:20 +0000 Received: by mail-vc0-f181.google.com with SMTP id ik5so944404vcb.12 for ; Fri, 19 Sep 2014 08:15:19 -0700 (PDT) MIME-Version: 1.0 X-Received: by 10.52.245.66 with SMTP id xm2mr700350vdc.36.1411139719343; Fri, 19 Sep 2014 08:15:19 -0700 (PDT) Received: by 10.53.9.162 with HTTP; Fri, 19 Sep 2014 08:15:19 -0700 (PDT) In-Reply-To: References: Date: Fri, 19 Sep 2014 17:15:19 +0200 Message-ID: Subject: Re: Handling Integration of Documentation From: Aljoscha Krettek To: dev@flink.incubator.apache.org Content-Type: text/plain; charset=UTF-8 X-Virus-Checked: Checked by ClamAV on apache.org 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 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 > 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 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 >> > 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 >> >> 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 < >> aljoscha@apache.org> >> >> > 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 < >> rmetzger@apache.org> >> >> >> 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 < >> >> aljoscha@apache.org> >> >> >> > 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 >> >> >> >> >> >> >> >> >> >>