forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <shan...@apache.org>
Subject Re: Separate CVS module for docs?
Date Fri, 12 Jul 2002 15:21:44 GMT

On Friday, July 12, 2002, at 09:25  AM, Nicola Ken Barozzi wrote:

>
> John Morrison wrote:
>>> From: Diana Shannon [mailto:shannon@apache.org]
>>>
>>> Your thoughts?
>> Dynamically created documents (jars.xml)?  Where would they
>> live/be generated/merged with other documentation?
>
> Good question.
>
> Centipede generates automatically xdocs about the build, and currently 
> we have decided to merge them together the actual documentation in the 
> build.context dir.
> This means that they are not put in CVS.

Agreed.

Live: If they are dynamically generated, they don't need to live 
*anywhere*. This is a problem with the current web site procedure (where 
we have a live site html repository with built docs)
Generated: Needed info/content could be accessed from other CVS modules 
in a variety of potential ways: locally (with path info to other CVS), 
remotely (viewCVS scrape or CVS-oriented cent )
Merged: Locally, based on result of build target (and then distributed 
wherever necessary). Even if we had a dynamic site with live 
documentation, would you really need this content always dynamic (or, 
say, refreshed every 24 hours, etc.).

If such a separate doc CVS exists, I think the people who want to play 
with and tweak the doc-building engine (in the doc cvs) as well as build 
custom docs (for distros or other needs) will probably be the same kinds 
of people who have multiple CVS repositories available locally. You 
could automate multiple CVS updates (via ant/cent) as well, to make sure 
dependencies are in sync. I also think it's overkill to assume *all* 
document users will need the CVS (and a doc-building engine) to get the 
docs they need. Let's just make fresh doc distributions easily available 
(via download, etc.)

It just feels like we have an overlap of concerns in the current CVS 
setup and docs are a secondary concern. Remote help from Forrest is 
nice, but I'd rather have a Forrest webapp instance (future industrial 
strength documentation framework) within a doc CVS. Otherwise, it just 
gets increasingly complex to see how future enhancements (CMS layers, 
etc.) can be implemented, especially when a dynamic site becomes an 
option.

-- Diana


Mime
View raw message