Mailing-List: contact forrest-dev-help@xml.apache.org; run by ezmlm
Date: Fri, 26 Apr 2002 06:25:06 -0400
Subject: Re: FAQ [was: Re: documentation architecture?]
Content-Type: text/plain; charset=US-ASCII; format=flowed
Mime-Version: 1.0 (Apple Message framework v472)
From: Diana Shannon <terracare@mac.com>
To: forrest-dev@xml.apache.org
Content-Transfer-Encoding: 7bit
In-Reply-To: <OKEDLKGMIPDOCJHOEDEFIENPDGAA.stevenn@outerthought.org>
Message-Id: <E0A9579D-58FF-11D6-BC54-0030653FE818@mac.com>


On April 26, 2002, Steven Noels wrote:

> My remaining emotion about this opposing-views-discussion is that I'm
> perfectly willing to massage DTD's into whatever direction we would
> like, but that we should decide on the 'when': we have legacy, but if we
> can convince more people to use Forrest because of the ease of
> information entry, and we have to change DTD's for that purpose, I'm
> perfectly happy.

Is it a Bad Thing to offer legacy as well as "new and improved" dtds? If 
Forrest provides tools for people to adapt their legacy content (to work 
with the new DTDs) would that still discourage Forrest adoption?

What if we kept the existing FAQ dtd and had multiple instances of FAQ 
data files, one per FAQ category?

> With regards to Literate Programming (i.e. Javadoc as a starter for
> 'human' documentation): I'm not convinced this is the ideal approach...
> the Cocoon documentation is in abysmal state partly because of the lack
> of 'connecting' documents, which provide a flow in between the
> component-based documentation snippets...

I agree, *none* of this works when so many content holes remain. Should 
we remedy the solution by reusing    and improving the content that 
exists or seek out more contributions?  One might believe -- given this 
thread of reusing documentation snippets -- that we have a scarcity of 
authors.  IMHO we don't have a scarcity of authors, simply inefficient 
mechanisms to encourage/capture their contributions. I think the greater 
number and variety of authors, the more effective the documentation 
effort will be for an open source project. It will be even better if 
content overlaps somewhat. Why? Open source developers typically 
introduce new conceptual models in their work. Many features of new 
releases remain underutilized by users -- even when some preliminary 
documentation exists for it. I think a diversity of voices/authors, each 
expressing an interpretation/application of this or that feature, is 
central to the community as whole in being able to grok these new 
conceptual models. This exchange occurs to some extent on the user 
lists, but it's generally incomplete, fragmented, and difficult to 
access. Our ability to tap into this community resource, and channel it 
(to the benefit of other users) into more meaningful document 
structures, is crucial.

How to do this? An early project, like POI, may need only a single 
"contribution" page. A more advanced project may need a whole section of 
pages and tools, with instructions and resources for community authors 
(similar to what I'm developing for Cocoon). Forrest could provide both 
sets of resources and leave it up to each project to decide what 
pages/tools to deploy and when...

Diana