forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nicola Ken Barozzi" <nicola...@apache.org>
Subject Re: documentation architecture?
Date Thu, 25 Apr 2002 12:32:21 GMT
From: "Diana Shannon" <terracare@mac.com>

> Is it within the scope of Forrest to offer projects suggested
> mechanisms/approaches/templates/schema for documentation? For example,

IMO yes.

> let's say a project had the following documentation offerings.
>
> documentation categories
> - FAQs
> - mini how-tos
> - guides (e.g., component-oriented)
> - tutorials
> - examples/cookbook "recipes"
> - case studies
> - reference guides
> - quick-reference guides
>
> For example, you may want to have:
> - "What's New" page within each documentation category
> - "Features" page (any document category)
> - Ability to search/browse within each documentation category as well as
> across all documentation categories, based on content, last modified
> date (thanks David Crossley).
> - Dataset scalability mechanism (e.g., when number of how-tos files
> grows too large)
> - Contributor's info (instructions/info, author/edit guidelines,
> how-tos, schema)

Please look at http://jakarta.apache.org/poi/ .

There is a menu on the left organized using the CDC principle:
Community-Docs-Code.

What does it mean?

A project at Apache seems to resolve around these three points.
The main thing is the community, without which nothing gets done.
Then the Documentation, which is the step to start understanding the
Community.
Finally the code, which is what the docs represent.

This ladder is usually climbed from the bottom: first you look at the code,
start reading the docs, and finally approach the community.

the scheme is somewhat like the one I include as an attachment.

I propose that we start from this basis and enhance it.

> Also, does Forrest's FAQ dtd (with all FAQ elements in a single file)
> properly anticipate processing/administering large numbers of FAQs,
> particularly when you factor in potential community contributions?

No AFAIK. The Faq DTD is a crucial poin that needs further discussion and
addressing, since it's basically the result of community know-how, the real
core of the project.

> Is it within the mission of Forrest to implement/provide these items?

Yes.

Now that I think of it, in the goals of Forrest there is a build system.

But now for the build there is Centipede, and I would remove that from the
goals.

This is what I envision:

Forrest: site (community+docs)
Alexandria: project code comprehension (docs+code)
Gump: module builds for quality assesment and CI(community+code)
Centipede: Build system to interact with all three.

Currently Centipede has a Gump descriptor and uses a modified version of
Forrest for the docs (committing today-tomorrow I still hope).
It also uses code documentation that I would like to see in Alexandria; I
didn't write it myself, and will ask maybe to donate it there.

What do you think?

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------




Mime
View raw message