db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Van Couvering <David.Vancouver...@Sun.COM>
Subject Re: [doc] More quality improvements to the documentation
Date Tue, 26 Jul 2005 18:13:22 GMT
Great work, Jeff, and great ideas.  Thanks for doing the research on 
adding user comments.  I think this is a very valuable feature so it 
would be really good if we could figure this out.  Let me know if there 
is any way I can help.

I also think the indexing is key to "maneuverability" in our docs, a 
common complaint I have heard about from new users: how do I find the 
documentation for what I'm trying to do?  Full text search would of 
course be great...

David

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