[Lazarus] Documentation and Help for Lazarus (content)

[Hans-Peter Diettrich]

Martin schrieb:

> 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.

Perhaps we should have an documentation tracker, where questions can be 
stored by everybody? The questions then can be linked to the existing or 
missing items in the overall documentation, and subsequent answers can 
become the base of the documentation to be added. Likewise links to 
existing (external) documentation or articles can be added to the links 
of the according help topics.

Useful documentation IMO is more a matter of organization or management, 
than of the goodwill to contribute to it. In so far it might be a good 
idea to open a new project, dedicated to the Lazarus documentation, with 
less restricted write access to everybody who has questions or answers. 
The related tools can be added to that project, again more open to the 
public than are the critical parts of the Lazarus project itself.



> 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?

Such general questions should be reflected in the help system, for every 
  topic. Different questions may apply to classes, methods, units, 
procedures etc. From an XML based view, the questions should reside in 
the structure part (XSD?), defining allowed and (optionally) mandatory 
parts (tags) of the entry data.


> 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...

This is why I think that filling the overall help system with questions 
and answers should not be restricted in the same way as is the code in 
the SVN repository.


> 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

One of my ideas is a help level, where the user can ask for more or less 
information by increasing or decreasing the level (comes close to 
expanding or collapsing nodes in an treeview), or restrict the displayed 
information to specific sub-topics.

DoDi