[Lazarus] Documentation and Help for Lazarus (content)

Martin lazarus at mfriebe.de
Fri Aug 21 01:14:34 CEST 2009


Another thing about the help. And i feel bad about saying this, because 
I really appreciate the effort that was made. And criticizing it without 
having contributed seems all wrong.
Never the mind, since we talk about it, I feel it should be mentioned

Some of the documentation still reads like a mockup, providing not more 
help than looking at the function itself.
I am trying to give an example how I think it could be improved. Just as 
a base for discussion


If I call help on a method from the LCL, I probably can look at the 
source code, especially if it's just a few line. So instead of an 
english representation of the pascal code (which may not provide any new 
info to me) I probably seek something like:
- what is it used for
- in which context is it used
- what happens / what else does it affect
- or why  is it needed

example
http://lazarus-ccr.sourceforge.net/docs/lcl/forms/tcustomform.notification.html

>
>   TCustomForm.Notification
>
> Notification calls inherited Notification then add or removes the 
> component's action list (depending on what Operation specifies)
>
this is what a look at the code immediately reveals. Maybe better:

"Called when the action-list linked from the form is destroyed, so it 
can be removed"


>     Declaration
>
> Source position: forms.pp line 497
>
> protected procedure TCustomForm 
> <http://lazarus-ccr.sourceforge.net/docs/lcl/forms/tcustomform.html>.Notification(
>
>   AComponent: TComponent 
> <http://lazarus-ccr.sourceforge.net/docs/rtl/classes/tcomponent.html>;
>
>   Operation: TOperation 
> <http://lazarus-ccr.sourceforge.net/docs/rtl/classes/toperation.html>
>
> ); override;
>
>
>     See also
>
> TComponent.Notification 
> <http://lazarus-ccr.sourceforge.net/docs/rtl/classes/tcomponent.notification.html>
>

First to be fair: a more proper explanation is given on the base-class. 
(see also)
This is the first problem: how much of the base class to repeat? Or how 
many links does the user have to follow to find what he seeks.

Many user will judge the help by the first page they get. Only if that 
page gave them some information they may seek further. The problem is 
especially if you search for a specific functionality, of which you do 
not know the name. So you press F1 on 2 dozens different methods, that 
may or may not be what you wnat (just because they sound as if they 
could). If you get 2 dozens times to a page, where you just have to 
follow another link ....


A short reiteration would be very helpfull:
(the wording needs some more effort, this was written on the fly only)

  Called to notify the Form  that another control has been destroyed (or 
otherwise removed).  [[ comment on a form ther is no insert operation, 
or is it? make it "removed or added" ]]
  The form checks if it refers to this control via it's "action list" 
and clears this property if necessary.
  It passes the information on to it's parent [link 
TControl.Notification] which can check for other properties that may be 
affected.

and then the See also link.
- The see also link could also contain a link to  TControl which is the 
next highr class to have this function (and provides information about 
further properties that may be cleared)
- the see also could repeat some of the links on 
TComponent.Notification, such as the link to FreeNotification or 
TOperation (anyway included in the declaration)

2nd and this is just my humble opinion (IMHO):  "calls inherited 
Notification,"
I do not think this is very usefull info (but I am aware that other may 
think so) or more to the point, the representation is not very good. See 
my example above.


Best Regards
Martin






More information about the Lazarus mailing list