On 11/02/2012 14:43, Hans-Peter Diettrich wrote:
Martin schrieb:
We have 3 cases
1) correct and good documentation. No note was ever attached, or if
it was, then it was in error and removal is appropriate
2) empty or meaningless. (can be seen of a kind of wrong, but not
"incorrect" or "untrue").
We do not need a note to tell the end user "This is meaningless/empty"
The notes are for the authors, not for the end user.
3) incorrect , untrue
Does not need a note. Does need immediate removal.
4 ff) incomplete, misleading, inconsistent...
This is the right place for notes, telling the *experts* to let their
experience shine here.
Notes that appear in the end user output are inappropriate.
Notes (off this kind) are communication between developers.
They can and should be accessible by those users, who want to see them.
But they are not content of the help.
Besides, the help system is a bad place. They are not very likely to be
seen by all the developers. After all the person who knows, does not
need to read the help
IMO you are miles away from practical documentation. Readers and
writers are not kind of compilers, which throw hints, warnings or
fatal errors on every word or phrase in a documentation. Most
developers think that their identifiers or implementations are self
explanatory. Users can have a very different experience with the same
items :-(
Which of your classes is applicable to a misspelled (or renamed)
reference? Including the right suggested action?
This is a different topic. I have not read any disagreement about the
idea to improve help.
Maybe about the "need" for individual items. But even if someone does
think an item does not "need" it, that does not mean, that an improved
text would be rejected. It only means that the person who does not feel
the need, will not do the work.
Such perception might be changed by discussion. But again notes are not
the place for a discussion.
-----------
If I think the menu entry "Jump back" (history) should be renamed, but I
do not have a better name, should I rename it do "Jump back [note: need
better name]" ? So every user who drops open the menu will see my note?
That might sound exaggerated , but is it not the same logic?
--
_______________________________________________
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
