[Vote] Automatic vs. Manual Documentation Structure

[Stefano Mazzocchi <st...@apache.org>]

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.
<st...@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------

Re: [Vote] Automatic vs. Manual Documentation Structure

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Stefano Mazzocchi" <st...@apache.org>

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

-1  reason:

>  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.

 as for

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

+0  Since it can get out of synch, I propose that a special Ant target
checks that all files in the dir are present; if not, it adds it to a
report, so we know its there but not referenced.

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

RE: [Vote] Automatic vs. Manual Documentation Structure

[Steven Noels <st...@outerthought.org>]

Stefano wrote:

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

+1, if we try to distribute the responsibility - each project should
maintain its own   structure file, perhaps distributed in .htaccess
style as described in my previous mail.

</Steven>