[Lazarus] Documentation and Help for Lazarus (content)

[Martin]

waldo kitty wrote:
>> 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 part of the problem is, that the person who writes the docs needs 
to already understand the code. But once you understand it, you look at 
documenting at a different level. That is because you knw the all the 
answer, you don't know which questions are out there.

In that respect (though I do not know how well this would work) part of 
improving the documentation would probably be that people without the 
answers (eg you waldo (no offense)) must ask them again. That is when 
you go to a help age you do so with a specific question in mind. if it 
isn't answered, then you can ask it.

The simplest would be to do so to the person who does the docs. but that 
wouldn't work, there would be do many questions. So you can go to the 
forum or the mailinglist. try to get the answer and then ask for it to 
be included. (even if it still needs rewriting)

The important thing is that you get a clear mind about what your 
question is.

It is NOT (or not only): What does this function do?

it is more likely:
- Why does this function do this?
- Why is this function needed?
- Where is it called?
- When is it called?
- What problem does it solve?
 eg. Notification solves the problem of having an object pointer , that 
points to a destroyed object, and would cause an access violation, if 
accessed

Maybe the answer was given on a related page, but a short summary should 
be included?


Another set of question arises from the opposite search. You know what 
you need, but you do not know what it's named.

You may need a function that tests if a checkbox is greyed (neither 
checked nor unchecked)
That is how you came to vie the help for the "checked" property. But 
that doesn't tell you anything about your problem. What it needs is an 
explanation that a third state exists, and that there is a property 
called "state".

Of course not every cross-reference you may think as valuable can be 
included. But this help can be provided by everyone. Only you need first 
get the answer from the mailinglist, forum or google...

Btw I think the above link should be included. But the problem is that 
the propery belongs to a base class (TButtonControl) and that only some 
but not all descendands have the "State" property. and you don't want an 
entry on Tcheckbox.Checked, that only explains the difference to the 
base. if you press help for TCheckbox.checked you want one page with the 
current + the additional explanation.

So this needs some form of controlable inclusion of the base-help 
managed by the help system


Best Regards
Martin