ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steve Loughran" <stev...@iseran.com>
Subject Re: New doc format and organization
Date Tue, 17 Oct 2000 19:17:39 GMT
> 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




Mime
View raw message