Upgrading and encryption...

[Ruslan Zasukhin]

On 4/7/06 2:37 AM, "Brendan Murphy" <bmurf at comcast.net> wrote:

>> Hmm, bad to hear this because we spend a lots time on docs for
>> 2.x. You could note it have grow in size about 3 times.
> 
> Because it has grown, it becomes more important to get the details
> right. A good example are the EVxxxx enumerations. We need not to
> just know what they are, but also their definitions. For
> example...
> 
> EVDbMode
> kDscDatBlbInd = 1
> kDsc_DatBlbInd  = 2
> kDsc_DatBlb_Ind = 3
> kDsc_Dat_Blb_Ind = 4
> kDscDatBlb_Ind = 5
> kDscDat_Blb_Ind = 6
> kDscDatInd_Blb = 7
> kDsc_DatInd_Blb = 8
> 
> We don't need to know the numerical value (it only encourages
> developers to skip the enum).

I NOT AGREE here.

> We do need to know what each
> constant means. Currently you have to hunt and peck through the
> documentation to find out what they mean.

Brendan,

V4RB_Reference -- this is REFERENCE of classes and methods.
it show you  

* declaration of method
* list of parameters and their short description
* description of method
* example
* possible errors
* references to other functions  "See Also"

REFERENCE document cannot and should not discuss deeply features.
For this exists 
    a) Valentina Kernel Manual
    b) Valentina SQL Manual.
    
I very wonder that you say that this is not correct.
I believe in the same way is organized documentation of other product you
use - REALBasic. Right? They have MANUAL and REFERENCE of methods.

IF you want to learn how work encryption FEATURE you need at first read
MANUAL and/or Wiki (we going move all manuals into wiki). Manual describe
the general concepts of feature, it show HOW TO issues step by step.
And only when you have learn feature you can go to Reference to see details
of some particular function.

YES this require time to learn. But Valentina 2 is BIG product. It is much
more bigger by features than Valentina 1.x

> You're right in the format hasn't changed much format wise since
> 1.x. Since it has grown quite a bit in size, therefore I think has
> out grown the format you have chosen. It is unwieldily to
> navigate. One thing you could do is publish a method signature
> only document as a reference sheet. Something the developer keeps
> on his desk.

You could note we have provide for each class on begging of section list of
all methods and properties.

But I see what you mean.

Believe me, we going to improve Valentina docs. We going even develop own
online doc system based on Valentina Server and PHP. But this is not
tomorrow, because when we have design it we have discover new features which
we can add into Valentina Database model to simplify a lots development of
such system. 
 
> Another approach is to use a topical format where the information
> is arranged by topics instead of by class. I find this format more
> user friendly for complex programs and Valentina certainly falls
> within that level of complexity.

You mean something like HOW TO ?

Right, and I think Wiki will help here a lots.
Wiki is great tool.

-- 
Best regards,

Ruslan Zasukhin
VP Engineering and New Technology
Paradigma Software, Inc

Valentina - Joining Worlds of Information
http://www.paradigmasoft.com

[I feel the need: the need for speed]