faq
flatforty
contribute
subscribe
configure
search
rdf
main
parent
thread
|
Re: How about updating help and context sensitive
by Joeri Sebrechts on Sunday 09/Sep/2001, @10:28
|
| You seem to know what should be in the help and in the context sensitive help. Maybe you could help the KDE team (which mostly consists of volunteers) by improving the help yourself. I'm sure it's not at all that difficult to do (as in, you don't need to know how to program to author the help). |
|
|
The Fine Print: The following comments
are owned by whomever posted them.
( Reply )
|
Re: How about updating help and context sensitive
by simon on Sunday 09/Sep/2001, @14:48
|
All the KDE apps I have tried to use have poor (generally sparse) help. (I might say, not as bad as man pages which overall should take the prize for "worst technical writing of all time")
Being realistic, it is way too difficult to write up-to-date help after the code has been done. For the developers it becomes a choice between new features/bug fixes OR documentation. No choice really.
Probably the only way that you have a chance is for the help to be embedded in the source code, and co-written with it.
Matlab takes the initial comment lines of the file as being help for that function, and I use this as the default help page for the gui screen created in that file. This is a simple and very effective system, that has resulted in almost all matlab functions written here, having documentation.
By comparison I just did a quick count of some in house VB and C: 11 of 74 documented main fn's, and only 1 of 5 apps with online help at all.
I think the help source needs to be in the files, right with the functions that respond to UI events, or in the UI builder as properties of the widgets. This context sensitive, widget bound help is the front line help of a gui app. By co-writing, it can become more useful. Written with the code it is likely to tell the use about known "gotcha's" and twists associated with using a feature. This is what the user is in the help for.
When it is written after the event, you get useless help that states the self evident: "The START button starts programs"
In delphi I use all the tooltips for documentation as these are so easy to edit as you go along. I would love Borland to put the context help editor in with the gui property editors, so you write the context help as you add a new widget.
-------------------------------------------------------------------------
Improving the overall standard of help is a job for the development tool writers.
If X hours of time is spent on an easy to use "help with code" system at the tool end, the results are multiplied by the number of application developers.
|
[
Reply To This | View ]
|
Re: How about updating help and context sensitive
by not me on Monday 10/Sep/2001, @14:55
|
Documentation is already integrated with the code, but it is documentation for programmers. User documentation on top of that would just clutter up the source files, I think, since user help isn't necessarily directly related to the various functions that are in the source. The underlying design of the program would start to leak into the user help and just confuse the user.
What is really needed is an easy way for non-programmers to create help files. Something on the order of KBabel (KDE's translator app) for help files. That way the programmers can concentrate on coding, ordinary people can have a nice way to contribute, and KDE gets up-to-date and useful help files!
|
[
Reply To This | View ]
|
|
The Fine Print: The previous
comments are owned by whomever posted them.
( Reply )
|
|
![[KDE Dot News]](http://www.kde.org/dot/Images/kdedotnews.gif)
