forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject [Vote] Automatic vs. Manual Documentation Structure
Date Fri, 15 Mar 2002 12:24:40 GMT
Ok folks,

this is a major issue and we have to decide what to do.

There are two solutions:

 1) Automatic Documentation Structure: the ToC is auto-generated out of
file system layout or database tree layout.

 2) Manual Documentation Structure: the ToC is manually created (as in
current book.xml files).

The first option is more technologically advanced, but has some major
drawbacks:

 a) it's implicit: in order to trigger a change in the ToC, the database
or file system must be changed and things moved around. This reminds me
of implicit parallel between the URI space and the file system space
which we now consider harmful.

 b) it's poor: how can we have external links in the ToC?

 c) it mixes concerns: who writes and stores the document is the one who
decides where it should go in the ToC. This is not the case.

So, even if the manual solution appears less technologically advanced, I
believe it's the way to go. This is the direction I vote to take, even
if this is in contrast with my past assumption (simply, I changed my
mind!)

Place your vote or alternative proposals.

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------



Mime
View raw message