[Lazarus] Documentation contribution

[Martin]

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?