Mailing-List: contact ant-dev-help@jakarta.apache.org; run by ezmlm
Message-ID: <027e01c0386e$ebf53e90$28d6000f@cvwls095>
From: "Steve Loughran" <steve_l@iseran.com>
To: <ant-dev@jakarta.apache.org>
References: <OFFAEE16D1.EF0BF272-ON8525697B.00537B5A@torolab.ibm.com>
Subject: Re: New doc format and organization
Date: Tue, 17 Oct 2000 12:17:39 -0700
MIME-Version: 1.0
Content-Type: text/plain;
	charset="Windows-1252"
Content-Transfer-Encoding: 7bit

> Hello all.
>
> I've been working over the docs a bit to reorganize them.  The current
> format of one bit index.html file is getting too unwieldy.  The next
> logical step is to use framesets with some sort of navigation pane.
> Unfortunately, I don't have time to build one that will work across
> multiple browsers before our ship date.  So, I've gone for a more LDP
> format that has a primary table of contents, with navigation links from
one
> page to the next.
>
> Now, I don't like this format as it introduces some maintenance headaches.
> However, in the end it is probably easier to read (better for the user),
> and it also gets us ready for when task docs get dynamically contributed.

I do agree that the docs need restructuring, but I am not convinced that
this new prototype is ideal.

-I quite like the tasks being in one file; my bookmark into the ant docs is
to index.html#tasks from whence I can click or scroll down to the task I
want. The unified style helps browsing and printing.

-If we could move to a structure which split the introduction and overview
pages from the tasks, and had some navbar alongside the tasks menu we could
get both easy navigation and a scrollable/printable file

-CSS usually works for defining a basic style sheet from a directory
relative URL; it is the fancy stuff ; DHTML, scripting and even DIV/SPAN
behaviour that varies across browsers. Keep it simple and most browsers are
happy.

-also I can see that you've used frontpage as the links assume new_ant_docs
is the filename. I would warn everyone against FP for that and case
sensitivity reasons.


Really dynamically generated docs are the way to go; if each task was
described in an individual file with no navigation/structure around it then
the one task per file document tree could be generated as easily as the
unified fileset; merging into a unified help file is also nominally
possible. Kind of an ant 2.0 feature though.

-steve