Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Jürgen Hestermann]

Am 2016-04-09 um 00:54 schrieb Giuliano Colla:
> I'm not an expert in avionics, but from my general knowledge even I could 
have told them the reason for pumping fuel from one tank to another, which is to 
balance the weight on the wings (fuel tanks are located on the wings). This 
function must be handled by some part of software related to the aircraft flight 
attitude most likely fully documented, but completely apart from the section which 
takes care of pumping fuel to motors!

Of course they knew that the general purpose of pumping aroung the fuel was for 
balancing reasons.
They only did not understand why it was done *in the current situation*. They 
did not expect that it happened at that time.
I do not know whether they understood it in the end but I thought it should 
have been clear and understandable immediately.


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Giuliano Colla]

Il 08/04/2016 18:56, Jürgen Hestermann ha scritto:
> 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.


This is more about *reading* the documentation, or maybe to 
*understanding* it, which is the subsequent step, once a decent 
documentation is available.


As the complexity increases, you cannot fit in the same page all the 
relevant information, and you must rely on reader's capability of 
understanding that what is stated at page 10 may carry implications to 
what is stated on page 900. This holds true for Airbus or Boeing, and 
for Lazarus and FPC.


I'm not an expert in avionics, but from my general knowledge even I 
could have told them the reason for pumping fuel from one tank to 
another, which is to balance the weight on the wings (fuel tanks are 
located on the wings). This function must be handled by some part of 
software related to the aircraft flight attitude most likely fully 
documented, but completely apart from the section which takes care of 
pumping fuel to motors!


A very similar case occurred with one of the first Airbus of Lufthansa. 
At landing it didn't stop at the end of the runway, and ended up in a 
cabbage field.

The subsequent investigation revealed that:

 * The Airbus had a protection preventing the reverse thrust if the
   landing gear isn't touching the ground. Reverse thrust was enabled
   only when all the wheels touch the ground.
 * Lufthansa procedure, in case of crosswind, is the sideslip landing,
   meaning the right (or left) wheels of the landing gear will touch
   ground much later.
 * As a consequence, in case of strong crosswind, reverse thrust was
   enabled too late.

It would appear that someone was unable to detect the problem generated 
by two fully documented facts, until an aircraft ended up in a cabbage 
field.


This sort of things do happen even when documentation is good, so let's 
imagine what may happen if documentation is poor or missing!


Giuliano



--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Ondrej Pokorny]

On 08.04.2016 20:19, Jürgen Hestermann wrote:

Am 2016-04-08 um 18:54 schrieb Ondrej Pokorny:
If everybody shared your approach, there wouldn't be anything like 
FPC and Lazarus. You should change your way of thinking.


You mean I should ignore facts?


Exactly.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Jürgen Hestermann]

Am 2016-04-08 um 18:18 schrieb Martin Frb:

Or the person reading the code with the intend of documentation, is more clever 
than this. They could report any suspicious parts, and clarify the intend. That 
way the code would be additionally be checked for bugs.
Bugs where the original implementer may have had a wrong understanding of what 
he was doing. In which case had the original coder documented it, the bug would 
have gone into docs.
Assuming the original coder is available for comment, then a person different 
from that coder can often write much better documentation. (simple because then 
2 (or more) people will have though about what it should be)


I aggree  that this can happen.
But it requires that the reader has at least the same skills
regarding the topic of what has been coded.
How long do you think would it take to (fully) understand the code for 
VirtualTreeView?
I have already found bugs in it but never understood why they occur
because I do not understand how the whole unit is coded.
So how should I even write documentation for it?


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Jürgen Hestermann]

Am 2016-04-08 um 18:54 schrieb Ondrej Pokorny:

If everybody shared your approach, there wouldn't be anything like FPC and 
Lazarus. You should change your way of thinking.


You mean I should ignore facts?

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Ondrej Pokorny]

On 08.04.2016 19:47, Jürgen Hestermann wrote:

Am 2016-04-08 um 18:38 schrieb Ondrej Pokorny:

On 08.04.2016 19:29, Jürgen Hestermann wrote:

But in the same way as others complain here about lack of coders
I am complaining about the lack of documentation.


Feel free to reduce this lack of documentation.


If I could only.
It would take me months to understand all the code
where the documentation is missing/wrong.


If everybody shared your approach, there wouldn't be anything like FPC 
and Lazarus. You should change your way of thinking.


Ondrej

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Jürgen Hestermann]

Am 2016-04-08 um 18:38 schrieb Ondrej Pokorny:

On 08.04.2016 19:29, Jürgen Hestermann wrote:

But in the same way as others complain here about lack of coders
I am complaining about the lack of documentation.


Feel free to reduce this lack of documentation.


If I could only.
It would take me months to understand all the code
where the documentation is missing/wrong.


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Jürgen Hestermann]

Am 2016-04-08 um 18:18 schrieb Ondrej Pokorny:
> 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.

I was answering to your statement: "If you think the documentation is bad, check the 
code and write it."
which was an answer to me writing: "When asking for documentation here I am often 
answered: Check the code."
I thought this was in general (at least my statements were).


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Ondrej Pokorny]

On 08.04.2016 19:29, Jürgen Hestermann wrote:

But in the same way as others complain here about lack of coders
I am complaining about the lack of documentation.


Feel free to reduce this lack of documentation.

Ondrej

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Ondrej Pokorny]

On 08.04.2016 19:32, Jürgen Hestermann wrote:

Am 2016-04-08 um 18:18 schrieb Ondrej Pokorny:
> 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.


I was answering to your statement: "If you think the documentation is 
bad, check the code and write it."
which was an answer to me writing: "When asking for documentation here 
I am often answered: Check the code."

I thought this was in general (at least my statements were).


Yes and I am answering to you in general: we do our best providing 
documentation. If you think we are not good enough, participate in 
writing documentation. What is the problem?


Ondrej

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Jürgen Hestermann]

Am 2016-04-08 um 18:18 schrieb Michael Thompson:

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.


Well, of course, nobody can be forced to do anything in open source projects.
The same applies to coding:
If nobody is willing (or not has the skills) to code for an open source project 
then it is as it is.

But in the same way as others complain here about lack of coders
I am complaining about the lack of documentation.
And IMO all discussions about what should be coded should also end in the 
question:
And who will document it?
Code without documentation is a pain.
Documentation saves a lot more time than it cost to write it.

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Michael Thompson]

On 9 April 2016 at 01:10, Jürgen Hestermann 
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
--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Martin Frb]

On 08/04/2016 18:10, Jürgen Hestermann wrote:


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".


Or the person reading the code with the intend of documentation, is more 
clever than this. They could report any suspicious parts, and clarify 
the intend. That way the code would be additionally be checked for bugs.


Bugs where the original implementer may have had a wrong understanding 
of what he was doing. In which case had the original coder documented 
it, the bug would have gone into docs.


Assuming the original coder is available for comment, then a person 
different from that coder can often write much better documentation. 
(simple because then 2 (or more) people will have though about what it 
should be)


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Ondrej Pokorny]

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

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Jürgen Hestermann]

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".


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[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.


Ondrej

--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus

Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation

[Jürgen Hestermann]

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.


--
___
Lazarus mailing list
Lazarus@lists.lazarus.freepascal.org
http://lists.lazarus.freepascal.org/mailman/listinfo/lazarus