[Lazarus] Documentation contribution

Martin lazarus at mfriebe.de
Sat Feb 11 19:11:33 CET 2012


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 at lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus





More information about the Lazarus mailing list