[Lazarus] Documentation contribution

waldo kitty wkitty42 at windstream.net
Mon Feb 13 04:15:02 CET 2012


On 2/11/2012 03:38, Felipe Monteiro de Carvalho wrote:
> On Fri, Feb 10, 2012 at 8:24 PM, Hans-Peter Diettrich
> <DrDiettrich1 at aol.com>  wrote:
>> I only remember that you stated that you don't like such notes.
>
> 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.

while i agree wholeheartedly, i must also support hans-peter's methods... 
especially since it may very well turn me toward an better explanation of the 
docs...

i cannot count the times that i've been ready to "toss in the towel" simply 
because the documentation has been sh!t3 :? either it is required to be 
connected online (the worst problem) or it takes super human effort to locate, 
down load and configure the docs as they should be,,, i've attempted such 
numerous times with the base and SVN packages but have failed each and every time :?

>> Such an entry is absolutely useless without instructions *what* should be
>> implemented at all. If you can't see that yourself, then you better keep
>> your hands off the documentation.
>
> It doesn't matter if it wasnt good before. Your [?] tags make it worse.

i beg to disagree... those "tags" make it easier to find the stuff that "doesn't 
make sense" (eg"[what?]") and that which needs better clarification... this is 
what is known as teamwork ;) in other words, there /must/ be clear communication 
between _all_ parties... as an outsider looking in, i much prefer the "dick and 
jane" type books... in other, clearer, words, give it to me as basic as you can...

>>> <p>[this looks outdated?]
>>> It is not outdated.
>> Thanks for confirming your ignorance :-(
> ...
>> If you had taken a look at Arc(), you certainly had noticed that the
>> parameters "angle1" and "angle2" do not exist any more. Do you need better
>> glasses?
>
> function Arc(DC: HDC; Left,Top,Right,Bottom,Angle16Deg,
> Angle16DegLength: Integer): Boolean; {$IFDEF
> IF_BASE_MEMBER}virtual;{$ENDIF}
>
> Then just change it to Angle16Deg and Angle16DegLength. From reading
> "looks outdated" how am I supposed to know that you mean that the
> parameter name is slightlt wrong?

how else would you expect to find a notation about it? "slightly wrong" is in 
acceptable... especially when one is relying on the documentation for 
clarification...

from my POV, the above exchange and such would have been pure gobbledegook even 
if i had been following along closely... :(

> As far as I remember I wrote this
> documentation, and it is not outdated, I just made a copy+paste error
> in the parameter name because the function is nearly identical to its
> twin sister from TCanvas and I was documenting both at the same time.

i see and acknowledge this but the main underlaying problem has been, finally??, 
identified and should be handled as needed... /even/ if it means that "notes" 
are visible... this allows others to handle the situation instead of just those 
who may have found it... i've seen more than one occasion where i've found a 
bug/problem that others have found before me... i have been thankful that they 
could show the same or a similar problem to mine...

i'm not too proud, with my 30+ years, to step back and say "show me, please" ;)




More information about the Lazarus mailing list