[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