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
--
_______________________________________________
Lazarus mailing list
[email protected]
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
