On 1/3/07, Rahul Akolkar <[EMAIL PROTECTED]> wrote:
On 1/2/07, Henri Yandell <[EMAIL PROTECTED]> 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 pages. 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 proejcts.apache.org should then be generatable (it's a layer above/below the doap files so we can't use those directly). 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 people.apache.org and projects.apache.org, I don't think it'll work well within Jakarta. Time to do some work - I'll stop rambling on :) Hen --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
