[Lazarus] Documentation and Help for Lazarus (content)

[waldo kitty]

Chris Kirkpatrick wrote:
> 
> 
> Martin wrote:
>> 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.
>>
> Thank you for your comments: I take them very much to heart. I have been 
> trying to get through most of the LCL classes, to produce at least SOME 
> documentation, and I agree that much of it is very simplistic, but yours 
> is probably the first useful feedback I have had, in several years of 
> work, and I thank you especially for this.

i'm glad to see that you took martin's comments in a positive light... i hope 
mine were taken in the same or similar light...

> As Waldo Kitty said in the next post, 'maybe someone who understands 
> geek but doesn't speak geek should be involved to "average joe" the 
> documentation'. I thought perhaps I was that average joe, being a 
> retired physician rather than a programmer.

i meant no disrespect or harm when i wrote that... indeed, not knowing who all 
is/was working on all the documentation kinda hampers that... i had no way to 
tell if it was coders or not... i do applaud the work done and know that it is a 
hard job to do... i've done it myself numerous times over the years which is 
also why i started off with "fighting with myself" because i wanted to say 
something but didn't want to offend anyone or say something taken the wrong way...

you probably are the necessary "average joe" and, as you pointed out, it is 
taking time because of the sheer volume to be documented... if i knew more about 
Lazarus, the LCL and related items, i'd be more than happy to offer a hand... 
however, i'm still struggling with doing object coding instead of procedural 
coding and then doing it in a GUI environment as well... one of the first things 
is to learn the existing objects and routines, how they work and how to use 
them... without good easy to read and understand docs (local or online) it is 
hard to do... plus one has to have a project to work on as well :P

maybe i'll convert my card game from text mode TP6 to GUI Lazarus/FPC?? hummm...

> Part of the problem is that several of the methods involved are 
> overridden at every level of inheritance: your example of Notification 
> is a good one, as every class that uses it overrides the ancestor, and 
> usually calls inherited Notification as part of its code. By the time 
> you get to the classes that actually appear as widgets on a Form, there 
> may be up to five or six levels of inheritance, each of which has added 
> an override to the original description of the method. How much should I 
> reiterate the information present in all the ancestors? I thought that 
> was one of the reasons we used links and 'seealso'.

speaking as a newcomer trying to learn Lazarus and FPC by using the available 
documentation, it is hard and confusing when you have to keep digging in deeper 
and deeper to fully understand what something does... then you have to back back 
out to where you were (if you can remember where you where when you branched) to 
travel down another path as well... and then another and another and another... 
my initial thinking on this is that possibly the highest level would contain 
info (briefly) on the deeper (inherited) aspects of the object along with a full 
description and working sample of its use like the built-in help in TP/BP... 
every entry for a built-in routine has a short working sample... as one walks 
deeper into the object's inheritance, they would loose only the higher layers of 
information and the current level would become the most detailed... yes, in each 
layer of the object would be links to the deeper portions...

> My proposal is that I concentrate on classes that are most immediately 
> apparent to the user/application programmer, the ones represented by 
> symbols in the component palette (or their immediate parent CustomXXXXX 
> classes), and produce as full a description as possible, along the lines 
> you suggest, even if it involves re-iterating some of the material from 
> more primitive levels. So I shall concentrate first on overridden 
> methods in StdCtrls, ComCtrls and ExtCtrls.

that sounds like a good plan to me :)

> Anyone with ideas for improvement is free to post a message, or even 
> better, submit a patch for improved documentation.

i hope to be able, one day, to do more than stand over here on the sidelines 
trying to figure out how i can do more to help the project while at the same 
time being able to use the project for my own coding needs...