Valentina documentation

[Robert Brenstein]

>On 5/6/05 3:26 PM, "Robert Brenstein" <rjb at robelko.com> wrote:
>
>Hi Robert,
>
>Yes, Valentina Kernel document is going to be splinted to few documents
>Or to have several parts:
>
>     Theory
>     API Description
>
>API description still will go by RB/Java style.
>I think this is the best style which mirror Valentina conceptions.

You should be able to express the concepts without needing a specific 
language. It may actually make things clearer for users unless you 
really want to cater to pro database developers only. Judging from 
list postings, there is a market for people who need and want to use 
database but are not database developers per se.

>I still think that API Description based on some ABSTRACTION layer also can
>be good...may be I am wrong.
>

I wonder exactly whether we need a document that presents API as 
abstraction. I am just not convinced that the abstraction is that 
helpful. The API for each environment IS different. As things are, I 
need to look up syntax in the doc for my environment and general API 
in kernel doc and translate the latter into what the former says.

Since your abstraction uses RB style, RB developers don't care except 
possibly having to look things up in two places. On the other end of 
spectrum, Revolution users suffer the most since the abstracted API 
bares little ressemblance to anything they code.

In my opinion, the abstracted API should be used only internally 
within Paradigma to guide the development and documentation efforts.

>
>  > I do realize that this would mean greater duplication of some things
>>  than now,
>
>Exactly. You should understand that it will be very hard as develop so keep
>in synchronization several big documents for different languages.

But you have to do it for the smaller documents anyway, so there is 
not so much extra effort. And you can put in charge the person 
responsible for developing the specific product.

I think that the extra effort will pay back. Lack or deficiency of 
environment-specific examples, beyond the trivial, has been a 
long-standing complaint.

There is also enough parallelism to set up a proper documentation 
management system that allows you to modularize all 
environment-specific docs.

Robert