db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From scott hutinger <s-hutin...@wiu.edu>
Subject Re: Derby documentation in PDF format
Date Tue, 12 Oct 2004 19:07:41 GMT
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,


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