flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Aljoscha Krettek <aljos...@apache.org>
Subject Re: Handling Integration of Documentation
Date Fri, 19 Sep 2014 15:15:19 GMT
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 <ktzoumas@apache.org> 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 <aljoscha@apache.org>
> 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 <uce@apache.org> 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 <aljoscha@apache.org>
>> > 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 <ktzoumas@apache.org>
>> >> 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
>> >> >> >>
>> >> >>
>> >>
>>

Mime
View raw message