[Lazarus] Documentation contribution

[Mattias Gaertner]

Martin <lazarus at mfriebe.de> hat am 11. Februar 2012 um 14:59 geschrieben:

>[...]



> 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"


"Empty" is clear.
But it is not always clear if something is "meaningless".
For example a description "loads a file" for a method LoadFromFile is like
stating the obvious. But when this term is translated it becomes helpful.



> > 3) incorrect , untrue
> Does not need a note. Does need immediate removal.


+1



> > >
> >
> > >> 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.


See the new fpdoc feature.


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


I doubt that this is practical. Creating one bug report per item would
create too much overhead. Creating bug reports with multiple entries does
not work well.



> > 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



Mattias
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus-ide.org/pipermail/lazarus/attachments/20120211/5f90ec73/attachment-0003.html>