[Lazarus] Documentation contribution

[Martin]

On 11/02/2012 16:49, Jürgen Hestermann wrote:
> Martin schrieb:
>>> 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.
> Why that? Better let the end user run into the open knife? I would 
> prefer to see such hints if someone already found that something is 
> incorrect or misleading. Of course, the best would be a consistent and 
> error free documentation but as long as this is not achieved such 
> hints are the second best IMO.
>

That is why I did not have topic 4. And my last answer is wrong.
(I have added my original 3 cases at the bottom of the mail, as this 
answer requires the context.)

- Misleading (falls under 3):
  equals incorrect. So it falls under 3 and should be removed.
However, if the person, who founds it has the ability to add a note, 
then he can also immediately correct it. Knowing it is misleading, does 
imply knowing what it was meant to say. So rewording the existing 
content should be possible.

It he person is not sure, about it being misleading or not, but believes 
it might be. Then better ask first before  adding a note

- incomplete (falls under 2, unless it makes in misleading, then falls 
under 3)
Does not change by adding a note.
Again, if the person knows what is missing, then he can immediately add 
it. Even if after adding in might still be missing some more.

- inconsistent (falls under 2, unless it makes in misleading, then falls 
under 3)
Same either fix, delete or ask


> 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"
>
> 3) incorrect , untrue
> Does not need a note. Does need immediate removal.