Re: [Lazarus] *** GMX Spamverdacht *** Re: Suggestion for TRadioGroup documentation
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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