[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