On 11/02/2012 17:47, Jürgen Hestermann wrote:
Martin schrieb:
> On 11/02/2012 17:21, Jürgen Hestermann wrote:
>> In general this is not correct. If I see that variables mentioned
in the documentation do not exist in the source I don't know
automatically which variables to replace them with (if any). Or when I
tested things and find that it does not behave as mentioned in the
documentation I also don't know how it's meant to work.
> And a comment/note like "[What]" or "[Really]" Does improve that?
At least it is a hint to the user to watch out and not rely too much
on the documentation.
A [what?] looks to me like I downloaded a broken file, so I will waste
my time on another download.
Anyway lets assume, question was raised, no one answered.
Then it is time to make sure, that something is wrong. Putting anythinc
that says "might be wrong" into absolute correct docs, is bad too (IMHO
worse). That is even so it only states the possibility. Any doc can
possibility be wrong, no need to state that unless one KNOWS it is.
If indeed it is, we can DISCUSS, if a proper worded text should be used
(at least looks more professional:
example:
The below documentation applies to an older version of the LCL. It might
not be entirely accurate.
BUT, that needs to be agreed by all.
> If anything more meaningful can be put into a note, then the person
can also write it proper into the doc.
> If your tests shows that it is incorrect. Well incorrect => delete.
> What good is "foo does blah blah [this is wrong]" over an empty
entry? Anyone who needs the old/outdated/wrong text, still finds it in
SVN
Of course, it all depends on the situation but there can be parts of
the documentation that give hints how it *could* be meant but nobody
knows how to make it correct. Then this is better than nothing.
--
_______________________________________________
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
--
_______________________________________________
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
