[Lazarus] Documentation contribution

[Martin]

On 11/02/2012 10:59, Jürgen Hestermann wrote:
> Felipe Monteiro de Carvalho schrieb:
> > It is not about liking, I think it is just plainly obvious that if
> > someone downloads our software and builds our docs, presses F1 and
> > reads [really?] it makes us look ridiculous so it is not acceptable to
> > have that in our documentation.
>
> Well, my opinion is: I would prefer to have a hint that something is 
> wrong in the documentation instead of letting me believe it is correct 
> if it's not. It's a kind of "watch out" which lets me have a closer 
> look when things do not work as expected. If you don't want this in 
> the documentation then *correct* it instead of reverting back to 
> faulty documentation.
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.

>
>
> >> Such an entry is absolutely useless without instructions *what* 
> should be
> >> implemented at all.
>
> That's the problem: If someone knows that it cannot be as documented 
> it does not automatically mean that he knows how it would be correct. 
> Still I would prefer to be informed about a documentation error 
> instead of letting me believe wrong things.
So we need a place to list those things.

The final doc (or anything that will be in it) is not the place.

Then (as long as we have nothing better) use the bug-tracker.  (I do not 
favour that, but it is the better place)

Or ask on the mailing list and fix, once you got an answer

>
> > It doesn't matter if it wasnt good before. Your [?] tags make it worse.
>
> I don't think so. It may be not very elegant. But you made it worse 
> again. Why didn't you take the hint and correct the documenation? That 
> would have been a real improvement.

Maybe he didn't know either