[Lazarus] Lazarus Digest, Vol 99, Issue 32

Alan Corey alan01346 at gmail.com
Fri Apr 8 20:33:57 CEST 2016 

Re: [Lazarus] Suggestion for TRadioGroup documentation

OK, I was just hoping for a sentence or paragraph to be added to the
documentation.  In HTML you group radiobuttons by giving every button
in the group the same name but different values.  I started with a
tgroupbox then went to a tradiogroupbox when it didn't work.  Still
got -1 for ItemIndex so I defined some with tstrings and got a
duplicate set, but itemindex works on those.  Aha!  But a radio button
that doesn't belong to a group isn't much different than a checkbox.

I agree with most things said about documentation except that nobody
has time to read it all.  And it can change, so you have to keep
rereading.  Being a multilingual project complicates things too.  When
I started in Linux I read (and printed) howtos, took them very
seriously.  But by the time I got around to doing what I was reading
about I found the howtos were years old and almost worthless.

I don't have my internal help working yet, and it may not be as good
as Delphi's when I do.  So I Google a lot.  Documentation that looks
like it came out of doxygen turns me off because so much of it's bad.
Good internal help may be a thing of the past.

I've seen bad documentation that looks like it was written by
fledgling technical writers and tells you obvious things. I agree, the
programmer is the ultimate reference/authority but I've had to
document projects and didn't enjoy it either.  So I think some
compromise like the newbie tech writer writes it and the programmer
checks/edits it might work.  How that works in a multilingual
environment I haven't a clue.

Really, I'm sort of trying out Lazarus again.  A year or so when I
tried it last I kept getting an error which, from Googling, I thought
came from the fact that OpenBSD basically has no working locale and
little interest in it.  So I gave up on using it.  Now I find it's
better, and when I get the error doing a "clean up and build" seems to
always get rid of it.  "Illegal character in format string" I think it
was.

On 4/8/16, lazarus-request at lists.lazarus.freepascal.org
<lazarus-request at lists.lazarus.freepascal.org> wrote:
> Send Lazarus mailing list submissions to
> 	lazarus at lists.lazarus.freepascal.org
>
> To subscribe or unsubscribe via the World Wide Web, visit
> 	http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
> or, via email, send a message with subject or body 'help' to
> 	lazarus-request at lists.lazarus.freepascal.org
>
> You can reach the person managing the list at
> 	lazarus-owner at lists.lazarus.freepascal.org
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Lazarus digest..."
>
>
> Today's Topics:
>
>    1. Re: Suggestion for TRadioGroup documentation (Michael Van Canneyt)
>    2. Re: *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup
>       documentation (J?rgen Hestermann)
>    3. Re: Suggestion for TRadioGroup documentation (Bart)
>    4. Re: *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup
>       documentation (Ondrej Pokorny)
>    5. Re: Suggestion for TRadioGroup documentation (J?rgen Hestermann)
>    6. Re: *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup
>       documentation (J?rgen Hestermann)
>    7. Re: *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup
>       documentation (Ondrej Pokorny)
>    8. Re: *** GMX Spamverdacht *** Re: Suggestion for	TRadioGroup
>       documentation (Michael Thompson)
>
>
> ----------------------------------------------------------------------
>
> Message: 1
> Date: Fri, 8 Apr 2016 17:35:46 +0200 (CEST)
> From: Michael Van Canneyt <michael at freepascal.org>
> Subject: Re: [Lazarus] Suggestion for TRadioGroup documentation
> To: Lazarus mailing list <lazarus at lists.lazarus.freepascal.org>
> Message-ID: <alpine.DEB.2.10.1604081729490.22583 at home.telenet.be>
> Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed
>
>
>
> On Fri, 8 Apr 2016, Graeme Geldenhuys wrote:
>
>> On 2016-04-08 15:54, Michael Thompson wrote:
>>> To be fair, a TGroupBox gets things dropped in it, and both nomenclature
>>> and look/feel are similar.
>>
>> I fully agree. As far as I can remember, even in my Delphi days I've
>> made that mistake of dropping radiobutton controls on a TRadioGroup.
>> Bart, it's not as obvious as you think. It's learning by error, and then
>> getting used to that fact.
>
> Or maybe read the documentation ? At least in the case of early Delphis
> that
> would have helped. (can't comment on current Lazarus)
>
> Thinking that you start without reading any form of documentation is an
> attitude which I highly condemn.
>
> Unfortunately, this attitude seems typical for IT.
>
> If NASA or Airbus or Boeing engineers would use that approach,
> I guess a lot of rockets, planes and whatnot would fall on our heads.
>
> I am glad they do not seem to have this attitude.
>
> Even cars come with a manual: usually located in the glove box, because
> your average citizen manages to open that without "Quick start guide".
>
> Michael.
>
>
>
> ------------------------------
>
> Message: 2
> Date: Fri, 8 Apr 2016 18:56:16 +0200
> From: J?rgen Hestermann <juergen.hestermann at gmx.de>
> Subject: Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for
> 	TRadioGroup documentation
> To: Lazarus mailing list <lazarus at lists.lazarus.freepascal.org>
> Message-ID: <5707E2B0.3030705 at gmx.de>
> Content-Type: text/plain; charset=windows-1252; format=flowed
>
> Am 2016-04-08 um 17:35 schrieb Michael Van Canneyt:
>  > Thinking that you start without reading any form of documentation is an
> attitude which I highly condemn.
>
> I would love to read documentations but very often there is none (or even
> worse it is wrong, outdated, confusing and incomplete).
> When asking for documentation here I am often answered: Check the code.
>
>
>  > Unfortunately, this attitude seems typical for IT.
>
> It has evolved into this.
> When I started with Turbo Pascal very excellent documentation was wide
> spread.
> Today with fast version cycling it seems that nobody has the time for it
> anymore
> or (even worse) not even has the knowledge about how things exactly behave.
> So we are all left to use trial and error which is realy sad.
>
>
>  > If NASA or Airbus or Boeing engineers would use that approach, I guess a
> lot of rockets, planes and whatnot would fall on our heads.
>  > I am glad they do not seem to have this attitude.
>
> I am not sure that they do not have it.
> I saw a report on TV about a test flight of the A380 some years ago
> where technicians were wondering, why the air craft computer was
> pumping fuel from one tank to the other in a certain flight situation.
> It seemed they needed a lot of time to find it out.
> I would have expected that the complexity was not driven to a point
> where even the engineers do not fully understand what they have built.
> Could be that we just had a lot of luck.
>
>
>
>
> ------------------------------
>
> Message: 3
> Date: Fri, 8 Apr 2016 17:59:28 +0200
> From: Bart <bartjunk64 at gmail.com>
> Subject: Re: [Lazarus] Suggestion for TRadioGroup documentation
> To: Lazarus mailing list <lazarus at lists.lazarus.freepascal.org>
> Message-ID:
> 	<CAMye31yBW2kY0tbgBgag+L=4kuM0uYKaPkpJF0bLhxh0+xmdLg at mail.gmail.com>
> Content-Type: text/plain; charset=UTF-8
>
> On 4/8/16, Michael Van Canneyt <michael at freepascal.org> wrote:
>
>> Or maybe read the documentation ? At least in the case of early Delphis
>> that
>> would have helped. (can't comment on current Lazarus)
>
> Yep, before the days of Internet, when I bought my copy of Delphi2, It
> had a manual.
> And even the I bought books on Pascal and Dephi and pressed F1 very
> often (Delphi in those days had a very good help file).
>
> (My initial TP 3.0 only came with a reader in Hebrew, which wasn't
> very helpfull since I'm Dutch)
>
> But even if you don't read a manual or something like that, and just
> play with the component, after just a few minutes you must have seen
> the Items property, played with it and see what it does?
>
> Bart
>
> Bart
>
>
>
> ------------------------------
>
> Message: 4
> Date: Fri, 8 Apr 2016 18:04:26 +0200
> From: Ondrej Pokorny <lazarus at kluug.net>
> Subject: Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for
> 	TRadioGroup documentation
> To: Lazarus mailing list <lazarus at lists.lazarus.freepascal.org>
> Message-ID: <5707D68A.1020206 at kluug.net>
> Content-Type: text/plain; charset=windows-1252; format=flowed
>
> On 08.04.2016 18:56, J?rgen Hestermann wrote:
>> When asking for documentation here I am often answered: Check the code.
>
> Yep. Correct. If you think the documentation is bad, check the code and
> write it. Alan, you are welcome to modify the domunentation in the LCL
> and send a patch. You can also freely update the wiki docs. There's no
> problem about it and you don't have to ask for permission.
>
> Ondrej
>
>
>
> ------------------------------
>
> Message: 5
> Date: Fri, 8 Apr 2016 19:05:24 +0200
> From: J?rgen Hestermann <juergen.hestermann at gmx.de>
> Subject: Re: [Lazarus] Suggestion for TRadioGroup documentation
> To: Lazarus mailing list <lazarus at lists.lazarus.freepascal.org>
> Message-ID: <5707E4D4.5020801 at gmx.de>
> Content-Type: text/plain; charset=windows-1252; format=flowed
>
> Am 2016-04-08 um 17:59 schrieb Bart:
>  > But even if you don't read a manual or something like that, and just
>  > play with the component, after just a few minutes you must have seen
>  > the Items property, played with it and see what it does?
>
> But then you only *think* you know how it works.
> It maybe that some conditions exist, when things behave different.
> You would never know about them if you have not read it somewhere.
> It could be that you just wonder why things *sometimes* crash (or
> whatever).
>
>
>
>
>
> ------------------------------
>
> Message: 6
> Date: Fri, 8 Apr 2016 19:10:20 +0200
> From: J?rgen Hestermann <juergen.hestermann at gmx.de>
> Subject: Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for
> 	TRadioGroup documentation
> To: Lazarus mailing list <lazarus at lists.lazarus.freepascal.org>
> Message-ID: <5707E5FC.1000508 at gmx.de>
> Content-Type: text/plain; charset=windows-1252; format=flowed
>
> Am 2016-04-08 um 18:04 schrieb Ondrej Pokorny:
>> On 08.04.2016 18:56, J?rgen Hestermann wrote:
>>> When asking for documentation here I am often answered: Check the code.
>>
>> Yep. Correct. If you think the documentation is bad, check the code and
>> write it. Alan, you are welcome to modify the domunentation in the LCL and
>> send a patch. You can also freely update the wiki docs. There's no problem
>> about it and you don't have to ask for permission.
>
> That's a bad idea.
> The person who wrote the code is the only person who knows what he
> intended.
> This person has to write the documentation.
>
> Not only that it would take a lot of (unneccessary) additional time to wade
> through
> foreign code (while the original coder already knew this after writing it).
> Also, every bug would become part of the documentation as it is "how it is
> coded".
>
>
>
>
> ------------------------------
>
> Message: 7
> Date: Fri, 8 Apr 2016 18:18:20 +0200
> From: Ondrej Pokorny <lazarus at kluug.net>
> Subject: Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for
> 	TRadioGroup documentation
> To: Lazarus mailing list <lazarus at lists.lazarus.freepascal.org>
> Message-ID: <5707D9CC.9000006 at kluug.net>
> Content-Type: text/plain; charset=windows-1252; format=flowed
>
> On 08.04.2016 19:10, J?rgen Hestermann wrote:
>> Am 2016-04-08 um 18:04 schrieb Ondrej Pokorny:
>>> On 08.04.2016 18:56, J?rgen Hestermann wrote:
>>>> When asking for documentation here I am often answered: Check the code.
>>>
>>> Yep. Correct. If you think the documentation is bad, check the code
>>> and write it. Alan, you are welcome to modify the domunentation in
>>> the LCL and send a patch. You can also freely update the wiki docs.
>>> There's no problem about it and you don't have to ask for permission.
>>
>> That's a bad idea.
>> The person who wrote the code is the only person who knows what he
>> intended.
>> This person has to write the documentation.
>>
>> Not only that it would take a lot of (unneccessary) additional time to
>> wade through
>> foreign code (while the original coder already knew this after writing
>> it).
>> Also, every bug would become part of the documentation as it is "how
>> it is coded".
>
> This doesn't apply to Alan's problem. We try to document important
> things. It's not our problem that "it is not enough stressed that
> functionality XYZ is not available on ZYX". We really don't have crystal
> balls to know what people may think is not enough stressed.
>
> Ondrej
>
>
>
> ------------------------------
>
> Message: 8
> Date: Sat, 9 Apr 2016 00:18:28 +0800
> From: Michael Thompson <mike.cornflake at gmail.com>
> Subject: Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for
> 	TRadioGroup documentation
> To: Lazarus mailing list <lazarus at lists.lazarus.freepascal.org>
> Message-ID:
> 	<CAKjh=-e3Ww29BLzD6vE6Bt4xpq3GHFA0q9r3dSBtd+ZubyJVkA at mail.gmail.com>
> Content-Type: text/plain; charset="utf-8"
>
> On 9 April 2016 at 01:10, J?rgen Hestermann <juergen.hestermann at gmx.de>
> wrote:
>
>> That's a bad idea.
>> The person who wrote the code is the only person who knows what he
>> intended.
>> This person has to write the documentation.
>>
>>
> That's a bad idea :-)
>
> Sure, *some* programmers make good documenteers, but in my experience
> they're the exception, not the rule.  My own documentation skills suck.
> Essentially, if you think like me you'll have no problems.  I'm very bad at
> seeing the problem from other people's perspective.  And I'm too old to
> change now.  I'm at the "shout louder if they didn't understand the first
> time" stage of life.
>
> I do agree though, we're open source.  We should all pull our own weight
> and not expect others to pick up our own slack.  It's only in a corporate
> environment that I'd insist on professionals doing the documentation.
>
> Mike
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL:
> <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20160409/2d3a0f2b/attachment.html>
>
> ------------------------------
>
> --
> _______________________________________________
> Lazarus mailing list
> Lazarus at lists.lazarus.freepascal.org
> http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus
>
>
> End of Lazarus Digest, Vol 99, Issue 32
> ***************************************
>


-- 
Credit is the root of all evil.  - AB1JX

More information about the Lazarus mailing list