db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Matrigali <mikem_...@sbcglobal.net>
Subject Re: [doc] More quality improvements to the documentation
Date Tue, 26 Jul 2005 19:18:30 GMT
I also miss global index, as francois said it was my main
tool to finding what I was interested in.  I can never guess
which book what I want is in.

Of course google search is an alternative, but indexes just
help me more sometimes.  My favorite question is something
like:
    There is a derby property, not quite sure how it is spelled, let's
    look in the index under derby.x and quickly scan and find the one
    I want and where it is documented.

Jeff Levitt wrote:

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

Mime
View raw message