[Lazarus] Documentation and Help for Lazarus

Hans-Peter Diettrich DrDiettrich1 at aol.com
Fri Aug 21 08:50:35 CEST 2009


Martin schrieb:

> That is why the docomentation on the wiki is so oft judged as having no 
> info on anything. Searche return plenty of matches, but even if you are 
> lucky and the right page is somewhere in the list, you still have to 
> search a lot of pages by hand.
> 
> Words in documentation often have special meaning, and often more than 
> one. They must either be marked in hte text, as being a keyword X, or 
> listed in a separate keyword list

Also: every author has a different opinion about appropriate keywords.

I found it essential that a central repository (database?) holds a 
documentation structure and keyword list(s), with a short definition of 
each entry. This repository should be updated by a documentation team, 
so that it remains consistent. Every piece of information has to be 
assigned keywords (attributes, tags) from that repository, so that it 
can be inserted in the right place.

> Example;
> 
> - Frame (also in plural Frames must much the same pages):
> There are at least 3 ways it can occur in the doc
> 1 - TFrame => visual form inheritance
> 2 - Stack frame
> 3 - just the plain English word.
> If you search for it, you should be asked if you mean 1 or 2.

This is one aspect, to be covered by above structure. When we collect 
enough search "patterns", it should be possible to identify a top level 
list of question types, along with a list of possible result categories. 
E.g. a search for "identifier" <name> can be qualified with any of
- short description
- long description, doc(s)
- implementation details
- declaration/definition (in unit...)
- compatibility/platform/widgetset, library
- bugs and problems
- examples, workarounds
- feature requests
- group (structural? functional? by task?)
- related
- overviews
- backgrounders
- tutorials, books
- author

The "group" result should be unique, otherwise above question about the 
meaning (which of the applicable groups is meant). Same for declarations 
in multiple units.

Every entry should have a "kind" and according attribute(s), e.g.
declaration: identifier:type in unit...
description: topic/identifier
example: task, related to...
overview: group, topic, related to...
backgrounder: related to...

An attempt to classify a couple of entries in the various information 
sources (units, libraries, fpDoc, wiki, Delphi, bug tracker, feature 
requests...) should return enough material for the construction of a 
structural skeleton. Possibly the sources can be scanned (indexed) 
automatically, resulting in a list of entries that wait for a 
classification and assignment of attributes.

For both the classification of entries and the later search, I could 
imagine a hierarchical representation of the applicable keywords or 
attributes. The first column contains the top level hierarchy, and a 
selection from a column fills the next column with applicable 
qualifiers, options or whatever is applicable. Or something like a 
master-detail view for the entire data base, opening upon a selection 
the next detail view instead of a new column.

Such a tool would simplify the classification of new material, helps in 
finding required (yet missing) subitems, etc.

DoDi





More information about the Lazarus mailing list