PDA

View Full Version : RE: Documentation Errors



Dennis Piccioni
2-Feb-2005, 11:47 AM
Hi Paul,

we are actually in the process of completely overhauling the Studio
help, that should address the Help button issues.

It does indeed feel like it is never ending. We are trying hard and
spending a LOT of time on doc. However, it's a HUGE project. I do feel
like we've made a lot of progress and we'll continue to chip away at it.

Regards,
Dennis


-----Original Message-----
From: Paul E. Richmond [mailto:paulr@ldm.com]
Posted At: Tuesday, February 01, 2005 5:50 PM
Posted To: visual-dataflex
Conversation: Documentation Errors
Subject: Documentation Errors


1) The help button on the Studio Application Properties is less than
helpful... (Like really man.)

2) When you finally do find the Version Information in Help, (Developer
Tools and Utilities > Studio > Building an application > Resources >
Version
Information) you will find that the hot-link to Program Properties is
broken.

3) The cVersionInfo link works but the relationship between what's
entered
in the application properties and what's provided in this class is NOT
clear.

4) What do the "Special Build" and "Private Build" checkboxes do?

Documentation.... the never ending curse.

--
Paul E. Richmond
IS Project Leader
L.D. McFarland Co.
(253) 572-3033

Peager
2-Feb-2005, 02:58 PM
Dennis,

You guys have been doing wonders overhauling help... I just want to
encourage you a little <VBG> to continue your efforts.

I normally 'report' documentation errors in the forum because it is too
cumbersome to do in your error reporting system... also, these types of
problems really don't have anything to do with my serial number, operating
system, day of the week, etc.

Not ranting....

Paul

--
Paul E. Richmond
IS Project Leader
L.D. McFarland Co.
(253) 572-3033
"Dennis Piccioni" <dennis-p@dataaccess.com> wrote in message
news:dCBdXbUCFHA.5740@dacmail.dataaccess.com...
Hi Paul,

we are actually in the process of completely overhauling the Studio
help, that should address the Help button issues.

It does indeed feel like it is never ending. We are trying hard and
spending a LOT of time on doc. However, it's a HUGE project. I do feel
like we've made a lot of progress and we'll continue to chip away at it.

Regards,
Dennis


-----Original Message-----
From: Paul E. Richmond [mailto:paulr@ldm.com]
Posted At: Tuesday, February 01, 2005 5:50 PM
Posted To: visual-dataflex
Conversation: Documentation Errors
Subject: Documentation Errors


1) The help button on the Studio Application Properties is less than
helpful... (Like really man.)

2) When you finally do find the Version Information in Help, (Developer
Tools and Utilities > Studio > Building an application > Resources >
Version
Information) you will find that the hot-link to Program Properties is
broken.

3) The cVersionInfo link works but the relationship between what's
entered
in the application properties and what's provided in this class is NOT
clear.

4) What do the "Special Build" and "Private Build" checkboxes do?

Documentation.... the never ending curse.

--
Paul E. Richmond
IS Project Leader
L.D. McFarland Co.
(253) 572-3033

Peager
2-Feb-2005, 02:59 PM
Oh yeah... one more thing. Being responsible for the documentation is my
personal vision of HELL!

Wishing you the best.

Paul

--
Paul E. Richmond
IS Project Leader
L.D. McFarland Co.
(253) 572-3033
"Dennis Piccioni" <dennis-p@dataaccess.com> wrote in message
news:dCBdXbUCFHA.5740@dacmail.dataaccess.com...
Hi Paul,

we are actually in the process of completely overhauling the Studio
help, that should address the Help button issues.

It does indeed feel like it is never ending. We are trying hard and
spending a LOT of time on doc. However, it's a HUGE project. I do feel
like we've made a lot of progress and we'll continue to chip away at it.

Regards,
Dennis


-----Original Message-----
From: Paul E. Richmond [mailto:paulr@ldm.com]
Posted At: Tuesday, February 01, 2005 5:50 PM
Posted To: visual-dataflex
Conversation: Documentation Errors
Subject: Documentation Errors


1) The help button on the Studio Application Properties is less than
helpful... (Like really man.)

2) When you finally do find the Version Information in Help, (Developer
Tools and Utilities > Studio > Building an application > Resources >
Version
Information) you will find that the hot-link to Program Properties is
broken.

3) The cVersionInfo link works but the relationship between what's
entered
in the application properties and what's provided in this class is NOT
clear.

4) What do the "Special Build" and "Private Build" checkboxes do?

Documentation.... the never ending curse.

--
Paul E. Richmond
IS Project Leader
L.D. McFarland Co.
(253) 572-3033

Knut Sparhell
3-Feb-2005, 05:40 AM
Dennis Piccioni wrote:

> we are actually in the process of completely overhauling the Studio
> help, that should address the Help button issues.
>
> It does indeed feel like it is never ending. We are trying hard and
> spending a LOT of time on doc. However, it's a HUGE project. I do feel
> like we've made a lot of progress and we'll continue to chip away at it.

From once being responsible for the documentation of a large
application I know so very well that such very easily become a never
ending nightmare. The size of the document is enormous, and the focus
on detail is extreme. All I can say is to change the people working
with it as often as possible, lowering the burden on each a bit. Over
time one develops a kind of blindness to the weakest parts, just as a
programmer gets blind to the weakest part of a large program.

The framework of todays help docs are good. Most of the newer stuff
added during the latest versions are well documented.

Disappointment occur when a new version is released with the old
"todo"-stuff is still in "todo", and when old style examples are still
in the old style and using obsolete stuff, even if updated June 2003.

------

Another thing is that some of the documentation seems to be using sloppy
code, as if the recommendations for proper code in general, and the
proper use of VDF code especially, is not respected even by DAW
programmers. Example from item_change doc:

procedure item_change integer fromi integer toi returns integer
integer rval
if (validate(self,fromi)) ne 0 begin
send bell
procedure_return fromi
end
forward get msg_item_change fromi toi to rval
procedure_return rval
end_procedure

First reaction: Huh? What does this do, really?

1. No Uppercasing of Keywords. Such "casing" of language keywords may
be done automatically by the Studio. Example code should be consistent
with this, as a recommendation for proper coding.

2. Integer variables not prefixed by i as recommended.

3. A procedure returns a value. Obsolete practice. Why isn't this a
function?

4. Procedure_Return statement used and it returns a value. "This
technique is now discouraged" says the documentation about
Procedure_Return. And I can add for myself that I think
Procedure_Return should be obsolete. It is a "goto" type of statement.
If blocks are recommended.

5. Because the procedure returns a value one has to use a strange
forward statement, using "msg_item_change". If this had been a
function it could have been Forward Get Item_change iFrom iTo To iRetval
as this is more i compliance with the usual and documented use of a
Forward statement.

6. "rval" used as the name of a variable. This is undescriptive naming.
The type and name of a variable should say something about what it
contains, what the value represents. Not just a "return value". What
does this return value mean? Is it perhaps a boolean status for the
operation? Or is it a validated "To" item?

7. The If boolean test expression is without outer parenthesis and the
"Ne" literal operator is used instead of <>. Such is obsolete, or at
least not mentioned in the list of legal expression operators.

Assuming Item_change is now an *event* function that returns the iTo
item number, the code could look like:

Function Item_change Integer iFrom Integer iTo Returns Integer
If (Validate(Self,iFrom)=0) Forward Get Item_change iFrom iTo To iTo
Else Begin
Move iFrom To iTo
Send Bell
End
Function_Return iTo
End_Function

Now, I can immediately see from the code that this function as a
validation event for a change from item iFrom to item iTo, returning the
proper item iTo, depending on the validation of the change operation.
I'm not sure if this is correctly understood, though.

Personally I use handles for items and prefix their names with hi, as
the value of an item reference is of no interest and seldom used for
calculation. I only use integers for whole numbers that has a meaning of
itself and may go into calculations.

Does such details matter, as long as it works? Well, it certainly makes
VDF look inconsistent with itself and being a bit too much filled up
with legacy stuff. As long as legacy stuff works there is no need to
promote its use through the docs. The trust in the framework, and the
learning threshold for new users, depend on this. I still feel like a
new user when I see such, being into VDF since 1999.

Keep up the good work being done.

--
Knut Sparhell, Norway