On 6/27/07, Gilles Scokart <[EMAIL PROTECTED]> wrote:
Actaully what I had in mind was :
+Home
+Download
+Documentation
+ Introduction
+ Settings
+ ...
+ Other Version Doc (a shorter name might be better)
+ trunk (I didn't think to that one, but it is an excellent idea !)
+ Introduction
+ Settings
+ ...
+ 2.0 alpha 1
+ Introduction
+ Settings
+ ...
+ 1.4.1
+ Introduction
+ ...
+ 1.4
+ Introduction
+ ...
Indeed, it makes sense. I don't know which version would be better to put as
the default (the one directly in documentation). The latest release would
probably be the best option. We might also in some cases provide direct
access to two versions. Another idea, put release notes and links to
download in documentation, and merge the download version history and
documentation. Something like:
+Home
+Download
+ Choose distribution
(no more other items here)
+Documentation (2.1-beta-1)
+ Release Notes (with links to download distributions)
+ Introduction
+ Settings
+ ...
+Documentation (2.0)
+ Release Notes
+ Introduction
+ Settings
+ ...
+ History
+ trunk
+ Release Notes
+ Introduction
+ Settings
+ ...
+ 2.0 alpha 1
+ Release Notes
+ Introduction
+ Settings
+ ...
+ ...
What was confusing was that I didn't realize that it was a naturaly
looking at the first menu that I used to know where I was, and
regularily missed the second tree menu.
Indeed, having only one menu solves this problem.
Concerning the remove of the since, I like the [since 1.4] processed by
xooki.
I'm also wondering about the tutorial. I think it should be updated
at each release, but I don't think we should keep the history online.
I think tutorials should be part of the documentation, and thus we should
provide the history online. For people "installing" Ivy as suggested in the
"go ivy" tutorial, they don't even download the release with the
documentation. So I think that providing tutorials history online is
helpful, because we can't know when people will move to a new version (when
we release a beta for instance). And if tutorials are part of the
documentation, it's no extra work.
Xavier
Gilles
2007/6/27, Xavier Hanin <[EMAIL PROTECTED]>:
> On 6/27/07, Gilles Scokart <[EMAIL PROTECTED]> wrote:
> >
> > I fully agree with the idea of separating the doc from the site, and
> > to keep the multiple version of the doc accessible on the site.
> > Using an 'svn reference' (I don't remember me the exact technical
> > term) to the branch of the doc is also a very good idea.
> >
> > However, I remember that the first time I saw the doc on jaysoft I was
> > little bit confused with the 2 menu blocks. Maybe having under
> > documentation (or after at the same level) a menu 'Older version'
> > would be more natural for the user. But it is maybe more difficult to
> > implement.
>
>
> If I understand well, you would like only one menu, with the site and
> documentation together, including other versions? Something like:
> +Home
> +Download
> +Documentation
> + trunk
> + Introduction
> + Settings
> + ...
> + 2.0 alpha 1
> + Introduction
> + Settings
> + ...
> + 1.4.1
> + Introduction
> + ...
> + Older versions
> + 1.4
> + Introduction
> + ...
>
> Is that what you'd like?
>
> I don't know exactly what was confusing with the jayasoft menu. Maybe
that
> the documentation menu was only displayed once you were in the
> documentation, thus requiring a documentation entry in the main menu,
with
> the details in another block. Maybe we could do something where the
> documentation menu block is always visible. When browsing documentation,
you
> would know which version you are browsing thanks to the page title (we
could
> suffix pages title with "| Ivy 1.4.1" for instance instead of "| Ivy").
To
> choose the version of the documentation you want to browse, we might put
ad
> hoc links on the documentation welcome page (
> http://incubator.apache.org/ivy/doc.html).
>
> The problem is that since this page is part of the documentation, we
can't
> add links to versions released after (on the 2.0 alpha 1 documentation
> welcome page, you wouldn't have link to 2.0). Unless we use a xooki
> component at the bottom of the page for that (and do not put the list of
> links in the page content directly). But this means that accessing the
non
> trunk documentation version requires two steps from the home page: go to
> documentation, then go to the version you want. You have no direct
access to
> the correct version from the menu. But you can still bookmark the online
> archived documentation. So I don't know if it's a good idea or not.
>
> Another option, add a link to the archived documentation in the download
> menu, under each version specific menu item. Something like:
> + Download
> + 2.0
> + 2.0.0-alpha-1
> + Documentation -> this would link to
> http://incubator.apache.org/ivy/2.0.0-alpha-1/doc.html, the welcome page
of
> 2.0.0 alpha 1 documentation
>
> But then corresponding doc menu would not be under this node, but in a
> separate block (the documentation menu block). Maybe not very intuitive.
And
> if the user go back to a page on the "site" (not the doc), the
documentation
> menu would now display the trunk documentation, which could be
confusing.
>
> Very often documentation is very separated from the web site itself
(Ant,
> spring, hibernate, ...). So maybe our problem is to try to make things
too
> integrated. Maybe we should have the site with a documentation page
> providing links to the documentations available (much like
> http://www.springframework.org/documentation), and then for each
archived or
> current documentation pages similar to the site, but with a
documentation
> only menu (no site menu), and only a link to the site home page (on the
top
> level logo for instance). Then access to the documentation always
requires
> two hits from the home page, but it's easy for users to bookmark the doc
> they use.
>
> This solution would be pretty simple to implement, and maybe less
confusing.
>
> I also think that if we keep the older version of the doc online, wqe
> > should remove the 'since 1.4' that we have (but keeping since 2.0 is a
> > good thing because it shows more clearly what is new).
>
>
> Indeed, it makes sense. Maybe to avoid loosing the information we could
use
> a separate CSS class for each since:
> <span class="since14">since 1.4</span>
> Then we would only need to change the CSS to hide the old since
information.
> With a little bit of javascript we could even use <span
> class="since14"></span>, and fill in the text with javascript. Or we can
> define a xooki filter, and put [since1.4] in our doc, which xooki would
> convert to "since 1.4" or nothing (to hide it). The advantage of this
last
> technique is that once generated the documentation does not rely on
> javascript to display proper "since" information. And we can also choose
to
> change the way to display the information (use a "new" icon instead of
> specifying since when it has been added).
>
> WDYT?
>
> Xavier
>
> WDYT?
> >
> >
> >
> > 2007/6/26, Xavier Hanin <[EMAIL PROTECTED]>:
> > > Could we conclude on this subject. I think we really need to improve
the
> > > access to archived versions documentation, and improve google
indexing.
> > >
> > > Thus I like Jan's suggestion: put the site - i.e. everything but
> > > documentation and tutorials - in a separate location in svn. My
> > suggestion
> > > is:
> > > https://svn.apache.org/repos/asf/incubator/ivy/site/
> > > Documentation would still be in project doc directory. Documentation
and
> > > site would be in two separate xooki, so we would have a TOC for each
of
> > > them, similar to what we got @ jayasoft, see this page for
reference:
> > > http://www.jaya.free.fr/ivy/doc.html
> > >
> > > On each release, we would package the documentation of the released
> > version
> > > (and not the site), and put this packaged doc on the web site in an
> > archived
> > > documentation section.
> > >
> > > Thus the web site would provide access to documentation of archived
> > releases
> > > (maybe we should limit this to three releases) and version in
> > development.
> > >
> > > We wouldn't use raw xooki pages on web site anymore, but generated
ones
> > > (mainly for google indexing). Updating the web site would require a
> > simple
> > > call to an ant target, which would generate the site and upload it
to
> > > people.apache.org. Same for the documentation of the version in
> > development.
> > >
> > > If nobody's object I'm ok to take care of that.
> > >
> > > What do you think?
> > >
> > > Xavier
> > >
> > > On 6/19/07, Xavier Hanin <[EMAIL PROTECTED]> wrote:
> > > >
> > > > On 6/19/07, Gilles Scokart <[EMAIL PROTECTED]> wrote:
> > > > >
> > > > > I like how the menu expands (the sublevel appears
progressively).
> > > >
> > > >
> > > > Yes, this is one of the nice effects with jquery.
> > > >
> > > > I didn't test the doc generation (I don't have a jdk 1.6 on my
machine
> > > > > :-().
> > > >
> > > >
> > > > I haven't tested either, I will do. Shouldn't be difficult to fix
in
> > case
> > > > of a bug.
> > > >
> > > > I notice a problem when I click on "tutorial" (the page, not the
> > arrow),
> > > > > the
> > > > > menu is not expandable anymore.
> > > >
> > > >
> > > > Good catch, the bug is indeed in all pages which are not at the
root
> > of
> > > > the doc directory. Will investigate and fix that asap.
> > > >
> > > > By the way:
> > > > > - Do we still need to generate the doc? (I guess yes, for
> > google. But
> > > > > there
> > > > > is maybe other solutions)
> > > >
> > > >
> > > > Which solution are you thinking about? Being badly indexed by
google
> > is a
> > > > huge drawback, so I think it's worth the pain of generating the
site.
> > When
> > > > I talk about a pain, it's very slight, since with a good target in
our
> > ant
> > > > file it's easy and straightforward (as soon as you have ant 1.7 +
java
> > 6
> > > > OR rhino in your ant lib - I haven't tested this last option but
we
> > should
> > > > be able to make it work).
> > > >
> > > > - Do you really want to publish the new site. I'm not sure, but
it
> > can
> > > > > contain doc of things that will only be released in 2.0-alpha-2.
> > > >
> > > >
> > > > This is something that can be discussed indeed. IMO I'd like to
have
> > the
> > > > history of old documentations (at least two last releases) and the
> > current
> > > > in development one on the site. With the file based approach we
have
> > it's
> > > > not too difficult, but for the moment we only have the latest one.
The
> > main
> > > > thing to do to get several labelled versions available on site is
to
> > > > separate the documentation from the site itself: we don't need to
put
> > an
> > > > history of the whole site was at one release, but only the
> > documentation
> > > > and tutorials sections). I should be able to do some javascript to
be
> > able
> > > > to extract a part of a xooki site automatically if you think it's
> > worth
> > > > it. For the last release ( 1.4.1), I think it would be useful to
> > provide
> > > > the doc online too, but I'm not sure we'll manage to separate the
> > sitefrom the doc.
> > > >
> > > > WDYT?
> > > >
> > > > Xavier
> > > >
> > > > Gilles
> > > > >
> > > > >
> > > > > > -----Original Message-----
> > > > > > From: Xavier Hanin [mailto:[EMAIL PROTECTED]
> > > > > > Sent: mardi 19 juin 2007 9:39
> > > > > > To: [email protected]
> > > > > > Subject: Re: Steps toward graduation
> > > > > >
> > > > > > On 6/12/07, Stefan Bodewig <[EMAIL PROTECTED]> wrote:
> > > > > > >
> > > > > > > On Mon, 11 Jun 2007, Xavier Hanin < [EMAIL PROTECTED]>
> > wrote:
> > > > > > > > On 6/11/07, Stefan Bodewig <[EMAIL PROTECTED]> wrote:
> > > > > > > >>
> > > > > > > >> On Thu, 7 Jun 2007, Xavier Hanin <[EMAIL PROTECTED]>
> > wrote:
> > > > > > > >>
> > > > > > > >> > - The code base must contain only ASL or
> > ASL-compatible
> > > > > > > >> > dependencies
> > > > > > > >>
> > > > > > > >> In the case of the non-ASLed JavaScript stuff I'd like to
see
> > a
> > > > > > > >> solution other than "we don't ship it" since legally
having
> > > > > > > >> something in svn means distributing it.
> > > > > > > >
> > > > > > > >
> > > > > > > > I can replace the dependency on ddtree by another js tree
> > > > > > > > component. We can use jquery [1] and the tree view plugin
[2]
> > for
> > > > > > > > instance. Both are released under a dual GPL and MIT
license
> > [3],
> > > > > > > > and MIT license seems to be compatible with ASL [4]. So,
may I
> > go
> > > > > > > > this way?
> > > > > > >
> > > > > > > Yes, the MIT license is compatible with the AL, so which one
you
> > > > > > > choose is a purely technical decision and that I leave up to
> > those
> > > > > > > who'll have to work with whatever is chosen 8-)
> > > > > >
> > > > > >
> > > > > > I've just checked in an upgraded version of xooki which does
not
> > rely
> > > > > any
> > > > > > more on ddtree: I've actually removed the dependency on a tree
> > > > > component,
> > > > > > recent tree components are usually able to deal with simple ul
/
> > li.
> > > > > So in
> > > > > > our case I've set up a jquery tree (MIT licensed) to manage
our
> > tree
> > > > > menu.
> > > > > > The modification is in svn, could someone try it before I
upgrade
> > the
> > > > > web
> > > > > > site?
> > > > > >
> > > > > > Xavier
> > > > > >
> > > > > > Stefan
> > > > > > >
> > > > > > > > [1] http://jquery.com/
> > > > > > > > [2]
> > http://bassistance.de/jquery-plugins/jquery-plugin-treeview/
> > > > > > > > [3] http://docs.jquery.com/License
> > > > > > > > [4] http://wiki.apache.org/jakarta/LicenceIssues
> > > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > --
> > > > > > Xavier Hanin - Independent Java Consultant
> > > > > > Manage your dependencies with Ivy!
> > > > > > http://incubator.apache.org/ivy/
> > > > >
> > > > >
> > > >
> > > >
> > > > --
> > > > Xavier Hanin - Independent Java Consultant
> > > > Manage your dependencies with Ivy!
> > > > http://incubator.apache.org/ivy/
> > >
> > >
> > >
> > >
> > > --
> > > Xavier Hanin - Independent Java Consultant
> > > Manage your dependencies with Ivy!
> > > http://incubator.apache.org/ivy/
> > >
> >
> >
> > --
> > Gilles SCOKART
> >
>
>
>
> --
> Xavier Hanin - Independent Java Consultant
> Manage your dependencies with Ivy!
> http://incubator.apache.org/ivy/
>
--
Gilles SCOKART
--
Xavier Hanin - Independent Java Consultant
Manage your dependencies with Ivy!
http://incubator.apache.org/ivy/
