commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Henri Yandell" <>
Subject Re: [all] What's in a distribution?
Date Wed, 03 Jan 2007 19:09:55 GMT
On 1/3/07, Rahul Akolkar <> wrote:
> On 1/2/07, Henri Yandell <> wrote:
> <snip/>
> >
> > I dislike the website being put in the distributions. It's a cheap way
> > to think you're documenting your project; but having the documentation
> > in there is good. I think the solution to this part is to make our
> > websites leaner (by moving things into Jakarta's site and nightly
> > builds) so that what is left is a better fit for going in the
> > distribution.
> >
> <snap/>
> IIUC, the cheap bit you are refering to is treating ${reports} as the
> entire documentation

that and the overlap between the website and the documentation. A
website is chiefly (I think) concerned with getting someone to a) use
the product and b) join in the community. The documentation should be
much about explaining how to use the product. So the front page for a
website and the frontpage for documentation are completely different

Reports are also useless on both the website and the documentation -
they're only really of value to the developer. The few that are of
value to the user shouldn't be under reports (imo) - license + javadoc
- neither are reports. A license report would have value to the user
(something that showed the license of all dependencies and linked to
information about them), but Maven doesn't have that afaik.

Reports should be a part of the CI system.

>, though am not sure how much value there is in
> breaking them off as you propose. In any case, components like [SCXML]
> have a multi-page cross-referenced user guide that is best viewed via
> a web browser, IMO, and that is unlikely to be distributed in any
> other form in the near future.

+1 for HTML as a format for documentation, definitely not arguing for
PDF or OpenOffice etc.

I've been grumbling about the above for a while - generally to myself
but every now and then to the list.

On the other side of things, I get grumbly about the Jakarta site and
thoughts on how to organize a Jakarta with lots of components in it.
One of my thoughts is that it should largely be database driven
(meaning an xml file like downloads.xml but for much more
information). Things like svn url, javadoc page, download page, web
page, nightly builds location. Even better is if most of these things
are name convention based: ie) 'scxml' gets used in each url.

The doap files for should then be generatable
(it's a layer above/below the doap files so we can't use those

Part of all that would be to take the common information out of the
component sites and into a Jakarta page for that component. Much like
the download section currently. The tricky part is one of l&f, it's
very odd to jump out of a site and into another site, however to have
a Jakarta with many components we have to step away from the common
l&f attempt we currently have (which I think just causes us pain) and
be more lenient.

One way around l&f pain is to generate an xml file for each page and
let the l&f be governed by the component. While I think that'll work
for pan-ASF things like and, I
don't think it'll work well within Jakarta.

Time to do some work - I'll stop rambling on :)


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message