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/
