[Lazarus] Documentation contribution

[Martin]

On 11/02/2012 21:10, Hans-Peter Diettrich wrote:
> Martin schrieb:
>
>>>> 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
>>>
>>> So I should add a note instead: "who can clarify this, please 
>>> contact me at <...> for my questions"? ;-)
>>
>> ask on the mailinglist....
>>
>> or did your smiley mean, you intentionally did mis-understand?
>
> You really don't understand the reality of providing documentation :-(
>
> Pick some of my notes, and ask the community for a clarification. Then
> wait...

Unfortunately your notes weren't committed. So (unless, I find the mail 
that points to mantis and then download the patch) I cannot read them

It is not the community to answer those question (so they can if they 
want), it is the developers.
And so far, IF one of them knew the answer, then I have usually gotten 
an answer (ok my question are usually what does this or that code do)

IF no one knows... But then those notes will not add any documentation 
either.

If there documetation that requires a comment like incomplete then it 
should get it in proper language "This documentation item is not 
complete" (potentially why / where / nhat)

However to deserve such a comment:
- it must not be obvious to the average user that it is incomplete
- the user must benefit from this knowledge

Similar for other notes.

Again: I am not for this. But that would IMHO be acceptable


>
>
>>> Please check how much I updated myself, *without* adding notes. The 
>>> notes occur only in those places, where I could *not* find the 
>>> correct description myself.
>>
>> Again as written before by me: If you actually have meaningful 
>> content, why a note?
>
> I've found all unmarked entries correct and complete (so far), so that
> the next contributor can concentrate on the marked items, and knows 
> what exactly to research. Feel free to explain an more efficient 
> approach, towards a complete documentation.

Nothing against marking then. but not in a way that goes into the final 
output.

Why are you changing subject?
This was not about marking entries (that possibility using comments has 
been mentioned before). This was about putting, things into the final 
end-user version.