flink-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ufuk Celebi <...@apache.org>
Subject Re: Handling Integration of Documentation
Date Fri, 19 Sep 2014 13:27:36 GMT
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
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message