[Lazarus] Extending FCL documentation

[Hans-Peter Diettrich]

waldo kitty schrieb:
> On 2/8/2012 15:36, Hans-Peter Diettrich wrote:
>> Sven Barth schrieb:
>>
>>> Not every feature is about source code. In this thread we're also 
>>> talking
>>> about IDE help (e.g. about its windows and its features) and not the 
>>> features
>>> of the underlying code.
>>
>> See my note on the difference between context sensitive help and 
>> (offline)
>> documentation.
> 
> ummm... in my old TP/BP 6/7 i hit F1 (cursor on an empty place) and get 
> a window (edit window) that pops up where i can choose from numerous 
> links...
[...]
> all of these are related to how to use the ide and have nothing to do 
> with examples of source code...

Right. The IDE has to find the help topics for the current IDE element, 
while the editor windows have to find help for the current identifier or 
keyword. This difference is reflected in the XML sources, where 
<element> refers to an identifier in source code, and <topic> for other 
descriptions. Unfortunately the IDE can decide to link to the wiki, 
which is available only when online - this is what many users dislike.

 > if i press SHIFT-F1, i get a beautiful
> index like one would find at the back of a book and that leads me to all 
> kinds of everything... ide assistance, code assistance, compiler defines 
> assistance, turbo vision stuff, etc...

Right, all that *can* be provided in a help system. It's a matter of 
organization and contribution and, finally, of the help viewer to 
provide a map (TOC) and an index.

In short: context sensitive help describes all *obvious* items, be 
identifiers or keywords in source code, or IDE menu entries or dialogs. 
Everything else is subject to the expectations and needs of the users, 
with *no predefined* (class, menu...) structure and content.

IMO documentation should transport know-how, starting with "Why should I 
use Lazarus?", down to more and more specialized topics. All these 
articles should be well structured and easily readable and 
understandable, not interrupted by technical details.

Everybody can write such articles, e.g. in the Wiki, but unfortunately 
this does not mean that such information can be *found* by other users. 
So we have to add (selected) contributions to the help system, and make 
them findable by e.g. links, keywords or topic lists. There exists no 
automatism that could do that automatically. Tags are not really 
helpful, because every contributor can have a different opinion about 
useful keywords, and a full-text search is typically too unspecific and 
contains too much unrelated "noise".


IMO we need a documentation structure in the first place, from which it 
becomes more obvious which topics should be added (overviews, 
how-to's...). Then we can start to fill that skeleton with topics like 
you mentioned before.

DoDi