db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Levitt <jlev...@Mutagen.Net>
Subject Re: Derby documentation in PDF format
Date Tue, 12 Oct 2004 21:04:58 GMT
Thanks again Scott,

Yes the main bottleneck in getting our information into DITA will be 
getting the doc content into the new format.  Once it is done, we will 
have vastly improved the quality of the documentation's retrievability.  
Add the fact that we will be single-sourced and able to create output in 
any format we want, and we have a good case for the conversion. 

I also appreciate the offer to help.  If no one has any objections or 
concerns, I will start working on this, perhaps first with the "Getting 
Started with Derby" book first as it is the smallest.  If I need any 
help, I'll take you up on your offer, Scott, as well as anyone else who 
may want to help.  Once the first book is converted, we can take a look 
at it and see if it works out for everyone, and depending on the wishes 
of the community, we can continue on with the conversion of the other books.

How does this sound?  If no one has any objections, I will begin working 
on this.


scott hutinger wrote:

> Yes Jeff, that does help get a better handle on portions.
> I think a lot of this information is that content isn't written in the 
> format it actually should be.  I think the real world defines this 
> very well, as going to a store and trying to dig into how the 
> information is sorted (most likely not), sometimes gets frustrating.  
> I think currently for Derby, since the documentation is within a 
> linear format, that portions of DITA are not really important as of 
> today, although possibly in the future this might become very 
> important.  I am very disappointed most of the time, trying to find 
> the information I want.  I see that DITA is trying to get writers to 
> think in a new manner or mode, which looks like it might fit within a 
> model that really is good.  I do think that even though the current 
> documentation may be within a linear format, it doesn't need to be 
> after put within DITA.
> I do see some very interesting use of this, not even related to 
> documentation.  For instance Sun Studio Creator has some pre-made 
> clips of "How to Use", which I think would be easy to incorporate 
> within DITA.  For those that use SQL once every couple years, that 
> would be handy, and could be 'embedded' within the documentation, and 
> pulled out easily.  Of course, of main importance, taking the current 
> documentation and getting it in a format easier to modify.  My 
> thoughts are that this looks like a very good step in a direction that 
> would fix the immediate needs of the mainline documentation with the 
> target being reuse.  Possibly some drawbacks might exist at the start 
> (unknown at this time), but I don't really think this is all that 
> important.
> I would have to thank Jeff for thinking about getting the 
> documentation in this format. :-)  Also, if any help is needed in this 
> area, I can give time to this.
> My thoughts only,
> scott
> Jeff Levitt wrote:
>> Thank you Scott,
>> To save you or anyone else who is interested some time, one of the 
>> documents at that site provides a great overview to the advantages of 
>> DITA.  It is located at:
>> http://www.oasis-open.org/committees/download.php/6637/DITA-technologyreview.pdf

>> It is 16 pages long, but you probably only need to scan the first 7 
>> pages or so to get a sense of what issues led to the creation of 
>> DITA, its advantages, and how it works.  The rest is more technical, 
>> down to the language level.
>> Hope that helps!
>> Jeff
>> scott hutinger wrote:
>>> I just thought others might like to know that looking at some of the 
>>> DITA information might be a bit on the verbose side, and might take 
>>> a bit more time to get feedback on this.  I am by no means a 
>>> document specialist, and I am a bit uncertain how many in this group 
>>> really are?   Possibly Jeff might be the best person to get any 
>>> information on 'what might be any possible objections'?
>>> DITA seems to look like a very good alternative to the current 
>>> problems in my view, but I just follow this group very closely, so 
>>> guess I don't count :-)
>>> But I have been looking at all the DITA information since this 
>>> morning, and thought I might be able to help a bit in this, but...a 
>>> lot of information to look over exists.
>>> From what I have seen, I think it looks great!
>>> scott
>>> Jeff Levitt wrote:
>>>> Jean T. Anderson wrote:
>>>>> Jonas S Karlsson wrote:
>>>>>> ...
>>>>>> I'm sorry if I wasn't clear. I consider our "src"-files (the .ihtml)
>>>>>> files to be generated, they were not written by a human:
>>>>> oops! thanks for the clarification!
>>>>> The *.ihtml files actually are the Derby source for the manuals.
>>>>> As I understand it, the Cloudscape doc set source is stored in 
>>>>> ArborText
>>>>> Epic. The IBM docs person generated files for Derby from Epic as
>>>>> multiple html files, then modified those to ihtml for forrest and to
>>>>> reflect Derby. --Also, I made a heavy pass through the ihtml docs as
>>>>> well before checking them into the subversion repository.
>>>>> The IBM docs person said it's easy to generate a single file per 
>>>>> book,
>>>>> but he doubted there was a way to reapply all the changes correctly.
>>>>> I see several options at this point:
>>>>> (1) Ask IBM docs to regenerate them as fewer files, then the Derby
>>>>> community applies all the changes that need to be made, starting from
>>>>> scratch.
>>>>> (2) Derby community starts (perhaps slowly) consolidating the 
>>>>> existing
>>>>> ihtml files into a more desirable format.
>>>>> (3) <==== your fine idea goes here =====>
>>>>> Incidentally a fewer number of files would have the benefit of 
>>>>> reducing
>>>>> the size and complexity of the forrest site.xml file.  A file gets
>>>>> associated with the site by an entry in the site.xml file.  If an 
>>>>> entry
>>>>> for that file is not there, forrest generates a left-hand 
>>>>> navigation tab
>>>>> with the entire site contents. It made me sea sick the first time I
>>>>> encountered it. If you want to see this effect, edit your local 
>>>>> copy of
>>>>> the site.xml to remove all but the "table of contents" and "index"
>>>>> entries for the manuals, do 'forrest site', then 'forrest run', then
>>>>> click on a page in one of the manuals.
>>>>> So, the current site.xml has an entry for every page in every manual.
>>>>> With the exception of the "table of contents" and "index" pages, 
>>>>> entries don't have a label so it doesn't explode that navigation bar.
>>>>> --Imagine 700 files listed in that navigation tab. One problem 
>>>>> remains
>>>>> that I haven't been able to figure out. The pages without a label get
>>>>> correctly associated with the Manuals tab (and that tab gets built
>>>>> correctly), but you lose context for the specific manual to which the
>>>>> page belongs.
>>>>> This problem would be solved by consolidating many files into 
>>>>> fewer so
>>>>> that all can be listed with a label in site.xml.
>>>>> -jean
>>>> I am the 'IBM docs person' that Jean and Jonas mentioned in their 
>>>> responses earlier.  I'm very glad to see that people liked the 
>>>> Cloudscape PDF's.  In a perfect world, I would have created a 
>>>> solution that would allow you to generate whole PDF's of each of 
>>>> the docs for Derby.  Unfortunately, I did not have enough time 
>>>> before I had to have a solution in place to contribute the docs to 
>>>> Derby, so my quick fix was to create the html for Forrest that you 
>>>> now find with Derby.
>>>> But now that I have more time, I have been trying to come up with a 
>>>> solution to several issues that the html presents, many of which 
>>>> have already been brought up in this discussion.  Indeed, html is 
>>>> not a very good source format.  Ideally, it would be nice to have 
>>>> XML source.  This would solve several problems.  First, we could 
>>>> use the XML to generate one PDF, or many html files, or just one 
>>>> large html file.  In effect,  we would have a single source that 
>>>> would allow us to output the documentation into any format we 
>>>> want.  In addition, the conversion to XML would remove these 
>>>> "blank" files that Jonas mentioned.
>>>> I would like to convert the Derby documentation to XML DITA.  DITA 
>>>> is an open-source initiative for creating XML-based documentation.  
>>>> You can find out more about the DITA open-source standard 
>>>> initiative at 
>>>> http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita
>>>> Converting to XML DITA solves the above problems, but also improves 
>>>> the QUALITY of the documentation immensly.  DITA allows you to 
>>>> create "articles" of information based on the books' contents that 
>>>> can stand alone on their own or within the book context.  ALL of 
>>>> the information in the 6 Derby books would be placed in articles 
>>>> that are classified as either concepts, reference material, or 
>>>> tasks.  In addition, we can further classify them as installation, 
>>>> configuration, development, adminstration, any many other 
>>>> descriptive catergories.  Then, users can sort the documentation by 
>>>> catergory, allowing them to look up only "development reference" or 
>>>> "installation tasks" etc, independent of the books.  And users who 
>>>> still want to use the book motif can use provided mapping files 
>>>> that automatically resort the articles into the proper order for 
>>>> each book and generate html, PDF's, etc.  DITA basically solves all 
>>>> of our problems and improves the retrievability of the documentation.
>>>> The conversion to DITA will take quite a bit of time. In the 
>>>> meantime, we could still use the current setup to modify the html 
>>>> files and build with Forrest.  But once the conversion is done and 
>>>> we recontribute the new doc set to Derby, I think the benefits far 
>>>> outweigh the delay.
>>>> I would be interested in what members of the community think about 
>>>> this proposal.  If there are no objections, I could begin work on 
>>>> this very soon.
>>>> Jeff Levitt

View raw message