Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Derby Development" <derby-dev@db.apache.org>
Received-SPF: neutral (asf.osuosl.org: local policy)
Message-ID: <20050726180007.67721.qmail@web81605.mail.yahoo.com>
Date: Tue, 26 Jul 2005 11:00:07 -0700 (PDT)
From: Jeff Levitt <derby@mylevita.com>
Subject: Re: [doc] More quality improvements to the documentation
To: Derby Development <derby-dev@db.apache.org>
In-Reply-To: <7921d3e405072610131bcfb906@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Transfer-Encoding: 8bit

--- Francois Orsini <francois.orsini@gmail.com> wrote:

> Looks good Jeff.
> 
> The original Cloudscape documentation had a
> fantastic master/global
> index file - it was my main front-door to me for any
> type of
> documentation searching - I could locate anything
> real fast and
> documents (HTML) were linked as well. I know this
> global index file
> took a lot of time to build but it did save so much
> time when looking
> for something in the documentation...
> 
> The MySQL online documentation also lets users add
> comments to the
> documentation - I have to admit it has been useful
> when I tried to get
> my way around MySQL....
> 
> Cheers,
> 
> --francois
> 
> On 7/26/05, David Van Couvering
> <David.Vancouvering@sun.com> wrote:
> > Ooh, yes, very nice.  This is something I have
> struggled with in the
> > past -- I click on a topic, and then to go to
> sub-topics I have to
> > 
> > I also very much like the related topics feature.
> > 
> > It would be great if those of us who use the
> manuals could "add" related
> > topics as it becomes clear they are related.  It
> would be even *nicer*
> > if this could be done right there online without
> having to edit DITA files.
> > 
> > If you look at the PGP documentation you will see
> what I mean:
> > 
> > http://www.php.net/manual/en/install.unix.php
> > 
> > at the bottom of the page there is the "add a
> note" link.  Users can add
> > notes to the page to provide more details, helpful
> hints, or
> > complaints.  There are quite a few helpful notes
> added to this page.
> > 
> > Wouldn't it be possible to modify the DITA
> template to allow users to
> > add notes?  We could then incorporate useful notes
> into the next rev of
> > the docs.
> > 
> > David

So I've actually been doing quite a bit of research
into doing something like inline comments to the
documentation, and I've run into several issues:
1. Both PHP and MySQL use the same engine for their
inline comments.  They use PHP scripting (of course). 
The problem is whether we can do that or something
similar on an Apache web site server.  I mean this not
in a technical sense (obviously we have the "ability"
to do it), but in a legal sense (whether Apache will
allow it). 
2. PHP and MySQL documentation aren't updated nightly
as ours is.  If we re-generate all of our
documentation nightly, wouldn't we lose that day's
comments from outsiders? The solution would be to have
the commenting engine store the comments in separate
files outside the content files themselves.  But then
what happens if we delete a topic or change it's name?
 Lots of infrastructure problems with this solution to
be worked out.
3. Again, if we use outside files to store the
comments, we return to the Apache legality issue.  Can
we do things like add and modify files on the Apache
servers?  I didn't think we could.

Now related links as we currently use them is another
story.  I would define our related links as strictly
links from one topic in a manual to another.  As David
requested, I think some sort of web page could be
created that has tables showing the relationships
between topics, and simple check boxes could enable or
disable related links between one topic and another. 
I think on a technical level, we would need to have
the engine behind this generate the relationship
tables for each book into separate files, then modify
the ant nightly build to merge the relationship tables
with the ditamap for each book before creating the
output.  The issue I see with this is who gets to
modify the tables?  Committers?  How would one request
a change?  Just through a JIRA entry, and then a
committer checks and unchecks the boxes on the web
page?

As for the global index, I think it is possible. 
First we have to get individual indexes working for
each manual, which we don't have yet either!  Scott
Hutinger and I did some research earlier this year
into implementing indexes but we were never able to
get it completed.  If and when we do that, then Global
indexing wouldn't be too far behind.  We already have
index entries defined within each topic dita file, but
they are just sitting there for now not implemented
anywhere.  Going back to the idea for a web page that
allows for creating and deleting our related links, I
think it could also be possible to create a section
where we can enter, modify, and delete index entries
for each topic.