[Lazarus] Documentation contribution

[Martin]

On 11/02/2012 17:02, Martin wrote:
> 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.
Now you cot me to the level where I trip myself, because rather than 
discussing the actual  issue, we try to prove the other one wrong, by 
dissecting teir words and find a meaning to them that wasn't thought off :(

my previous answer is not wrong: Notes are inappropriate.

my previous answer was incomplete


> (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.
>
>
>
> -- 
> _______________________________________________
> Lazarus mailing list
> Lazarus at lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus