[Harbour] Re: Documentation storm on user's list
στις 29/05/2010 10:40, O/H Przemysław Czerpak έγραψε: This is my last massage in this thread. I strongly suggest to invest resources necessary to create such long messages about how to create harbour documentation in creating some real documentation. It will be really productive. best regards, Przemek To (Przemek, Viktor and co-developers) I understand that you, the leaders of Harbour, along with a bunch of very capable and helpfully dedicated developers, have undertaken an abandoned-on-the-shelf project and have made it such an outstanding programming language with an unparalleled quality, similar to which is not easy to find in the FOSS arena. We the standalone HB_users, mostly ex-clipper programmers, feel very happy, lucky and blessed to have you in the head of this great-great project: - happy because we were here to see it happen, - lucky because we have (someone more, someone lesser) _benefited_ by your generously offered product, product of your hard work - blessed because (well, i 'm not such a religious man to speak about it, let say that..) we just feel it so! I guess that some of us, being motivated by such thoughts, we're seeking ways to give back whatever we think could help the project, give back not as a payment but rather as a moral obligation . Sadly i see that till now the results is a mixture of plenty of good intentions along with much disturbing noise. It really doesn't help! To mumbling, in the event, our apologies does not help either. Maybe the best thing we could do is to follow your suggestion, that is, to try to invest resources necessary to create such long messages about how to create harbour documentation in creating some real documentation. [The only problem here is the very real case where some user (for many reasons, eg. lack of time, lack of knowledge, inefficiency in writing etc) is unable to create some real documentation but still he wants to contribute. That was the aim to create a Harbour-Foundation but since you consider that it'd produce more problems than it'd solve, we can let the proposition peacefully rest into recycle bin of the never-said]. Once again, we[*] feel the need to express ours warm thanks and sincere appreciation to your great work. Many-many thanks for your patient too! --- Pete [*] and before any fellow reader comes and question me: who have made me the spoke-person of Harbour users, i must clarify that i 'm not pretend that i represent anyone, nor i am doing it intentionally! it's only because i find it humanly normal to express an opinion, it's only because we sometimes have to speak about things that touch our common interests, but also because this _dumbness by the users side_ is unfitting to thinking people, and certainly discouraging and disheartening for the developers! [forgive me if you find my words are wrong and/or upsetting, but Please let's take, from time to time, the chance to reply to them just to say 'thanks'. eventually, it seems that still it counts more than we guess...] ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
[Harbour] Re: Documentation storm on user's list
pete_westg wrote: στις 27/05/2010 13:02, O/H Viktor Szakáts έγραψε: By documentation friendly code i mean two simple and very well known things. a. Short introductory description on top of source code (in place of this long and more or less useless copyright reminding replica ) b. in-line comments. c. sample program. [OK, they are three, but any combination of two will perfectly do the job ;)] I think it should be MANDATORY to post comments in the sources of all PUBLIC functions, especially type HB_FUNC() and APIs, with a description of parameters and return. If You do fix a function that causes a change in parameters or return that You MUST be correcting a comment for this function. Adam -- View this message in context: http://harbour-devel.1590103.n2.nabble.com/Documentation-storm-on-user-s-list-tp5107834p5124785.html Sent from the harbour-devel mailing list archive at Nabble.com. ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: Documentation storm on user's list
Hi All, ..I'd prefer to we follow a Harbour-Fund financing model. That is, we start making donations to a common-treasure and let project leaders decide and make hiring agreements for manual creation, or whatever would help project's improvement. But, of course, let's hear other harbour followers opinions. xHarbour.com has excellent documentation and for last four or five years they have not been able to sell enough copy to receive back money they had to pay for professional documentation writer. And here we have ready product not sth what may appear in the future. If ready to use product cannot be sold in enough number of copies then for sure we have no chance to collect enough money for sth what does not exist yet. Instead starting such foundation may be the end of Harbour. It will not allow to collect enough money to pay professional documentation writer but it may be the source of never ending discussion when the documentation will have been finished addressed to me and some other core developers. I'm not slave of Harbour users and for sure I will not tolerate such messages for long time. This is my last massage in this thread. I strongly suggest to invest resources necessary to create such long messages about how to create harbour documentation in creating some real documentation. It will be really productive. Very well summed up. Small addition: _Asking others_ to create a fund (just like doing the same with docs) won't help the case either (I also don't have any notion to deal with any sort of common money, as discussed a few times in the past). Pls note that _anyone_ is free to create a fund and deal with the sponsoration of doc writing, or any other matter whatsoever. Harbour admins/core developers aren't needed for this. To make it clear: I'm personally not interested in writing docs even if paid for, and other core developers has stated this clearly too in the past. [ After waiting some days for the original thread on user's list taking any sort of constructive direction, I had made the decision to ban the thread starter, on the grounds that he went into an unstoppable monologue, which is off-topic regarding Harbour user's list, and really doesn't help to solve any problems. ] Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: Documentation storm on user's list
2010/5/31 Viktor Szakáts harbour...@syenar.hu: Pls note that _anyone_ is free to create a fund and deal with the sponsoration of doc writing, or any other matter whatsoever. Harbour admins/core developers aren't needed for this. In italy if i receive money from internet (to pay doc writing for example) i must pay tax To make it clear: I'm personally not interested in writing docs even if paid for, and other core developers has stated this clearly too in the past. Very clear [ After waiting some days for the original thread on user's list taking any sort of constructive direction, I had made the decision to ban the thread starter, on the grounds that he went into an unstoppable monologue, which is off-topic regarding Harbour user's list, and really doesn't help to solve any problems. ] We must search a way to solve problems I have pending same mail where requesting free clipper doc Viktor -- Massimo Belgrano ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: Documentation storm on user's list
This reads like one of your nice commit logs! On Mon, May 31, 2010 at 9:35 AM, Viktor Szakáts harbour...@syenar.huwrote: [ After waiting some days for the original thread on user's list taking any sort of constructive direction, I had made the decision to ban the thread starter, on the grounds that he went into an unstoppable monologue, which is off-topic regarding Harbour user's list, and really doesn't help to solve any problems. ] Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
[Harbour] Re: Documentation storm on user's list
στις 29/05/2010 00:42, O/H Pritpal Bedi έγραψε: Ok, I commit to write documentation, how much you will pay ? Certainly not less than the current market price[*] for similar products. (and of course, I'd prefer it to be an under-official-leadership initiative.) Users of Harbour can pledge how much one is willing to pay, pledge only on this list, do not pay now, and if the total figure will match my expectations, I will start writing. You will pay when I will at certain stage. For sure, your suggested terms are fairly reasonable, however.. Accepted ? ..I'd prefer to we follow a Harbour-Fund financing model. That is, we start making donations to a common-treasure and let project leaders decide and make hiring agreements for manual creation, or whatever would help project's improvement. But, of course, let's hear other harbour followers opinions. [*] Okay! plus the beers, at the release-day feasts. ( 12 bottles maximum and no more.. ;) ) ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: Documentation storm on user's list
2010/5/29 pete_westg pete_we...@yahoo.gr στις 29/05/2010 00:42, O/H Pritpal Bedi έγραψε: Ok, I commit to write documentation, how much you will pay ? Certainly not less than the current market price[*] for similar products. (and of course, I'd prefer it to be an under-official-leadership initiative.) I promise pay to fund 500$ suggest explain a determined number of money the price is result od number of intrested I made a sosftware that cost 500.000 $ if i jave 10 possible customer my price will be 5$ instead of customer are 100.000 price is 5$ imo Harbour documentation not have a similar products Users of Harbour can pledge how much one is willing to pay, pledge only on this list, do not pay now, and if the total figure will match my expectations, I will start writing. You will pay when I will at certain stage. For sure, your suggested terms are fairly reasonable, however.. Accepted ? yes ..I'd prefer to we follow a Harbour-Fund financing model. That is, we start making donations to a common-treasure and let project leaders decide and make hiring agreements for manual creation, or whatever would help project's improvement. But, of course, let's hear other harbour followers opinions. The difficult is due by different low,our fund is worlwide Our fund must intested to people Pritpal will simply open a paypall account In italy for example i can't receive payment without invoice -- Massimo Belgrano ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: Documentation storm on user's list
On Sat, 29 May 2010, pete_westg wrote: Hi, ..I'd prefer to we follow a Harbour-Fund financing model. That is, we start making donations to a common-treasure and let project leaders decide and make hiring agreements for manual creation, or whatever would help project's improvement. But, of course, let's hear other harbour followers opinions. xHarbour.com has excellent documentation and for last four or five years they have not been able to sell enough copy to receive back money they had to pay for professional documentation writer. And here we have ready product not sth what may appear in the future. If ready to use product cannot be sold in enough number of copies then for sure we have no chance to collect enough money for sth what does not exist yet. Instead starting such foundation may be the end of Harbour. It will not allow to collect enough money to pay professional documentation writer but it may be the source of never ending discussion when the documentation will have been finished addressed to me and some other core developers. I'm not slave of Harbour users and for sure I will not tolerate such messages for long time. This is my last massage in this thread. I strongly suggest to invest resources necessary to create such long messages about how to create harbour documentation in creating some real documentation. It will be really productive. best regards, Przemek ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: Documentation storm on user's list
http://tech.blog.aknin.name/2010/05/29/mailing-list-debates-considered-harmful/ Most important thing is the title. Have fun! :-) []'s Maniero ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
RE: [Harbour] Re: Documentation storm on user's list
-Original Message- From: pete_westg [mailto:pete_we...@yahoo.gr] Sent: Thursday, May 27, 2010 9:19 PM To: harbour@harbour-project.org Subject: [Harbour] Re: Documentation storm on user's list [...] When I am saying documentation is more valuable than coding, in no way mean that coding is nothing. It just means that without documentation, many parts of code is almost unusable, for many people (users). For me the most useful examples. For now I miss examples how to bind query in OCILIB :) Tomorrow I would like two parallel inquiries in OCILIB (there is no examples, but there should not be a problem in MT). There is also an example of a LIBCAIRO to place their pictures. Examples (tests) in this moment of development are more useful than the documentation. The project is developing very quickly, and documentation would be quickly outdated. And our ability to (at least mine) to adapt to what is already in the examples is delayed by about two years (eg in managing HTTP). I am very happy with the examples, the more that I do not know English, and my contact with him is limited only to this group. I could not understand the documentation, examples much faster. Regards, Marek Horodyski ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
[Harbour] Re: Documentation storm on user's list
στις 27/05/2010 23:33, O/H smu johnson έγραψε: Some thoughts, On Thu, May 27, 2010 at 12:18 PM, pete_westg pete_we...@yahoo.gr mailto:pete_we...@yahoo.gr wrote: are you sure you have understood my words? I 'm afraid you don't! What I am not sure for, is the reason for this misunderstanding. Perhaps, is it due to my bad English or what? - Stating that Harbour's lack of documention is straightly against to the spirit of open source initiative can be considered offensive by many. Who made you the spokesperson of the Open Source movement? It could be interpreted that your statement means their years of work were done improperly. Please don't put words in my mouth that i never said. Or please show me even one instance of the word Harbour into my first post to which you are referring. There is not one! You have just tailored a phrase, by mixing your assumptions with cut-n-past parts of my lines, to base your claim that this (the tailored) statement can be considered offensive by many. I wonder what is the purpose of this conversation. Is it to accuse me, for my comments being offensive, strange, insulting, bugging or whatever? I can't say to someone do or don't feel offended. All I can do is to explain my point, and wish that through understanding, the reasons that make someone to feel offended would vanish. So, i must make it clear, that when i wrote documentation is (or must be) on upper top, in the scale of open source priorities, since documents, or better the lack of documents, is straightly against to the spirit of open source initiative (this is my unaltered phrase) i was not referring specifically to Harbour but rather i was expressing a general point, regarding the whole opensource case. and I believe, you don't need to be a spokesperson of the OS movement to speak up your thoughts about it. I have a sentiment that the problem in present days is not just the open source code. you don't need to be a specialist to see it. Trillions lines of very good code have been written and quadrillions will be written in the close future. It is really amazing and all the respect belongs to the great developers. On the other hand we can't ignore the fact that we already have an infinite ocean of source code inside which we (the community/society) could sink or we could sail. I vote to sail! and the ship to sail and not sink, you guess it, is the documents. To put it an other way, the crucial subject today, is not any more the open source code. It is (and always was) the open knowledge. And knowledge without documentations is simply impossible. Documentation is the vehicle of knowledge. documenting is to securing the ability to be able to use the brilliant machines that brilliant developers-brains have created. Now, Viktor will come and accuse me: Empty words, again. Yes, I see it. I see the emptiness in the absence of manual. I see the emptiness in my inability to be useful in the subject. And the question is still here, as you Viktor, say. Why we have no documentation? Why we have such a brilliant and huge amount of excellent code, like Harbour has become thanks to your (and all of developers) tremendous efforts and not an analogous documentation? We said, it is difficult to create documentation. but if we think it better, difficulty is not the main reason. The main reason is that nobody wants documentation so much, nobody is burned to create it. and the deeper cause of this, is the lack of belief to the great value of a documentation, is the lack of belief to the vital significance of a manual, it is because we are much eager for source code and we are not interested for documentation, perhaps because is not so glorious to write documents compared to code-writing. obviously we lack a documenting culture( similar to coding culture), and for this to happen, perhaps we need empty words, even to just have something to filling up, even to just have something to keep the spark alive. as i see it there two directions. to get rid off of this documentation blah-blah, which means that we'll immediately stop bugging you the developers, or to keep searching ways how the goal of documentation will become true. Honestly, Viktor, i 'm not interest to bugging you, (i don't know what exactly the bugging is, or means, but if it is related to the activity of a bug, then i think it's my time to start feeling offended. However, feeling offended or not, doesn't cure my real displeasure to feel almost guilty because i can't find a practical way to effectively contribute documentation. ___ P.S. Strangely enough, i see no reaction to the challenging idea of harbour-xhb merging. Does the harbour community think it was a joke or this deafening silence express their glacial indifference about the future of Harbour? --- Pete ___ Harbour mailing list
Re: [Harbour] Re: Documentation storm on user's list
To put it an other way, the crucial subject today, is not any more the open source code. It is (and always was) the open knowledge. Nobody ever promised that knowledge or mastery will automatically fly into the users' brains, just by having access to the information, be it open source, blueprints, scientific papers or the wikipedia. Pls remember that even such _quite well documented_, _fully open_ and long time known systems as Linux, have several companies _earning_ large sums of money by supporting them (f.e. Red Hat), selling workforce who do actually understand the system and _translates_ that to knowledge for the benefit of customers/users, even in the form of documentation. All of these require an _effort_. You can do this effort yourself, or you can ask other to do that. In latter case, you either pay for it or motivate them by other means. Second option seems more complicated with documentation (than with code) as it is huge work and the one who does it doesn't benefit from it in too many ways. Looks like it's not enough to give something for free to expect any sort of return for it. Why we have such a brilliant and huge amount of excellent code, like Harbour has become thanks to your (and all of developers) tremendous efforts and not an analogous documentation? See above. We said, it is difficult to create documentation. but if we think it better, difficulty is not the main reason. The main reason is that nobody wants documentation so much, nobody is burned to create it. and the deeper cause of this, is the lack of belief to the great value of a documentation, is the lack of belief to the vital significance of a manual, it is because we are much eager for I think nobody ever questioned that documentation and samples are nice and useful, or even crucial. That was never a question. Viktor, i 'm not interest to bugging you, (i don't know what exactly the bugging is, or means, but if it is related to the activity of a bug, then i think it's my time to start feeling offended. However, feeling offended or not, doesn't cure my real displeasure to feel almost guilty because i can't find a practical way to effectively contribute documentation. Bugging is: write documentation friendly code, create samples, create good comments Did you notice I created INSTALL, with 330 updates in the last 15 months? Did you notice Przemek creating lots of e-mails which are better than most written documentation, or not to mention xhb-diff.txt, which is almost like an academic paper? Or I could mention docs created by Pritpal for HBIDE. Can you imagine how much time does it take to create these thing? If you don't, just keep on asking for more, or telling what you tell, you risk that some will find it as bugging. Overall, I see no lack in lead by example here... The problem is there is nobody to follow. Demanding more without appreciating work already done is probably the surest motivation killer [ especially in open source, where appreciation is the most important (or only) motivation factor ]. ___ P.S. Strangely enough, i see no reaction to the challenging idea of harbour-xhb merging. Does the harbour community think it was a joke or this deafening silence express their glacial indifference about the future of Harbour? It wasn't a joke. Viktor ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
[Harbour] Re: Documentation storm on user's list
στις 28/05/2010 15:23, O/H Viktor Szakáts έγραψε: Pls remember that even such _quite well documented_, _fully open_ and long time known systems as Linux, have several companies _earning_ large sums of money by supporting them (f.e. Red Hat), (I don't know if this has been proposed before but) why don't you create some kind of Harbour Fund? It could be used to accept donations, contributions and, why not, for hired services (be it on-line help or code-writing or support etc.) --- Pete ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
[Harbour] Re: Documentation storm on user's list
pete_westg wrote: (I don't know if this has been proposed before but) why don't you create some kind of Harbour Fund? It could be used to accept donations, contributions and, why not, for hired services (be it on-line help or code-writing or support etc.) Ok, I commit to write documentation, how much you will pay ? Users of Harbour can pledge how much one is willing to pay, pledge only on this list, do not pay now, and if the total figure will match my expectations, I will start writing. You will pay when I will at certain stage. Accepted ? - enjoy hbIDEing... Pritpal Bedi http://hbide.vouch.info/ -- View this message in context: http://harbour-devel.1590103.n2.nabble.com/Documentation-storm-on-user-s-list-tp5107834p5114768.html Sent from the harbour-devel mailing list archive at Nabble.com. ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
[Harbour] Re: Documentation storm on user's list
El 27/05/2010 11:16, Horodyski Marek (PZUZ) escribió: Viktor, ... Harbour is beautiful, beautiful, and once again fast :) Best regards, Marek Horodyski Amen Some hummor (really?) to ease the day ;) http://www.kevinwilliampang.com/2008/08/28/top-10-things-that-annoy-programmers/ Enjoy Angel ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
[Harbour] Re: Documentation storm on user's list
στις 27/05/2010 13:02, O/H Viktor Szakáts έγραψε: To Pete, [ Sorry to reply here, but I'm readonly user of users-list. ] Strange and insulting thoughts towards anyone who have dedicated huge amount (many years) of (maybe even full time) to take this project where it is now. Maybe you could elaborate on what you mean by documentation friendly code... If coding means nothing to you, pls delete all the Harbour sources and try to use it after... Viktor, [I finally managed to discover that my post in users-forum had been replied here. so, here it is my humble yet belated answer] are you sure you have understood my words? I 'm afraid you don't! What I am not sure for, is the reason for this misunderstanding. Perhaps, is it due to my bad English or what? And how did you find insulting thoughts, there where it doesn't exist? When I am saying documentation is more valuable than coding, in no way mean that coding is nothing. It just means that without documentation, many parts of code is almost unusable, for many people (users). We all agree with you that if every individual harbour user would be willing to write some (small) part of documentation, the Harbour manual would perhaps be already here. But life has shown that it is not that simple. Months ago we have had the very same discussion. many people had then declared their interest to contribute, some of them had shown their valuable ideas and had made specific proposals. Unfortunately after a while the interest had faded out, and the only real remained/result was an documenting extension into hbide, which supposedly would help to write documentation. I have tried to use it. It didn't work (not in operational meaning of the term). Beyond this, i 've had spent hours digging into sources, trying to format some pieces of documentation. the results were not significant. why? because writing documentation is indeed difficult, actually is more difficult than somebody can imagine and for sure more difficult than coding. that's why, i suppose, for every thousands good coders correspond few -very few or even none- good documenters. Regarding your definition of idealism, i couldn't put it better. thinking, learning, contributing and/or paying is the only realistic approach. Starting from the later, please don't have any doubt that I (and I believe many other Harbour users) would be more than willing to _pay_ for a manual if anything did exist. Contributing is another crucial story. Nobody's _demanding_ anything from developers. And how one could do that? But asking for documentation should not considered as a demand. Is a very normal and absolutely expected query for any newcomer to Harbour. The do it yourself is a pushing away answer. What insulting do you find in this paragraph? By documentation friendly code i mean two simple and very well known things. a. Short introductory description on top of source code (in place of this long and more or less useless copyright reminding replica ) b. in-line comments. c. sample program. [OK, they are three, but any combination of two will perfectly do the job ;)] P.S.: merging harbour-xhb? (wow! this question could be a real philosophical dilemma). although this is a core-developers decision, you better don't have doubts that the great majority of the users, in case they'd been asked for, would loudly vote No! --- Pete ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
Re: [Harbour] Re: Documentation storm on user's list
[I finally managed to discover that my post in users-forum had been replied here. so, here it is my humble yet belated answer] are you sure you have understood my words? I 'm afraid you don't! What I am not sure for, is the reason for this misunderstanding. Perhaps, is it due to my bad English or what? And how did you find insulting thoughts, there where it doesn't exist? When I am saying documentation is more valuable than coding, in no way mean that coding is nothing. Yes, it read just that way. Maybe one day someone will teach me how to write documentation instead, so something valuable can be done at least. Maybe some day someone will teach us how to create documentation friendly code in my free time. It just means that without documentation, many parts of code is almost unusable, for many people (users). We all agree with you that if every individual harbour user would be willing to write some (small) part of documentation, the Harbour manual would perhaps be already here. But life has shown that it is not that simple. Months ago we have had the very same discussion. many people had then declared their interest to contribute, some of them had shown their valuable ideas and had made specific proposals. Unfortunately after a while the interest had faded out, and the only real remained/result was an documenting extension into hbide, which supposedly would help to write documentation. I have tried to use it. It didn't work (not in operational meaning of the term). Beyond this, i 've had spent hours digging into sources, trying to format some pieces of documentation. the results were not significant. why? because writing documentation is indeed difficult, actually is more difficult than somebody can imagine and for sure more difficult than coding. that's why, i suppose, for every thousands good coders correspond few -very few or even none- good documenters. We didn't need HBIDE documentation extension, and we still don't need it to create docs. Unfortunately all our attempts to solve documentation quickly becomes a tool frenzy. Maybe when such pops up, you should voice your opinion in time. The only upside of last discussion is that we more or less nailed out the final NFDOC documentation format, but not enough that anyone would feel to pick it up and continue (or tell something better). Regarding your definition of idealism, i couldn't put it better. thinking, learning, contributing and/or paying is the only realistic approach. Starting from the later, please don't have any doubt that I (and I believe many other Harbour users) would be more than willing to _pay_ for a manual if anything did exist. Contributing is another crucial story. Unfortunately if users are willing to pay for what doesn't exist, it won't help us the smallest bit. Plus the existing xhb documentation is available for money since years, yet nobody buys it. So what am I missing? All I see is empty words. Nobody's _demanding_ anything from developers. And how one could do that? But asking for documentation should not considered as a demand. Is a very normal and absolutely expected query for any newcomer to Harbour. The do it yourself is a pushing away answer. What insulting do you find in this paragraph? Demanding and asking are two very different things, and it's usually easy to tell apart after having some time spent on public forums. Demanding: Asking others to do something. Asking: Asking a question in an interactive or productive fashion. Notice that the latter sometimes may even be considered as contribution. Huge difference. By documentation friendly code i mean two simple and very well known things. a. Short introductory description on top of source code (in place of this long and more or less useless copyright reminding replica ) b. in-line comments. c. sample program. [OK, they are three, but any combination of two will perfectly do the job ;)] I find this largely offensive. Did you check the code for comments? What exactly do you expect, hidden full blown documentation inside the source? Sample programs: all developers have done their fair share, so pls don't continue bugging us with it. But, the short and generic answer is: DO IT if you miss it. All I see is you criticizing from the high ground without even considering how much work is what you ask for, and how much work has been done totally unnoticed by you... You seem to miss the ground rule of open source: everyone does something to scratch an itch. Some of us many times do much more than that, but pls don't ask for more, more and more, just do it. P.S.: merging harbour-xhb? (wow! this question could be a real philosophical dilemma). although this is a core-developers decision, you better don't have doubts that the great majority of the users, in case they'd been asked for, would loudly vote No! While your conclusion is valuable, perhaps
Re: [Harbour] Re: Documentation storm on user's list
Some thoughts, On Thu, May 27, 2010 at 12:18 PM, pete_westg pete_we...@yahoo.gr wrote: are you sure you have understood my words? I 'm afraid you don't! What I am not sure for, is the reason for this misunderstanding. Perhaps, is it due to my bad English or what? - Stating that Harbour's lack of documention is straightly against to the spirit of open source initiative can be considered offensive by many. Who made you the spokesperson of the Open Source movement? It could be interpreted that your statement means their years of work were done improperly. - Saying that this is a real problem with wider consequences than you can imagine is also a pretty offensive. Are the Harbour developers incapable of determining what might happen if there is a lack of documentation in the near future? I think they can. And not only that, but hearing a vague statement like this is like hearing someone claiming that the world is going to end in 2012, in ways we can't possibly fathom. It sounds like you are saying the Harbour project is doomed unless developers start complying with your documentation suggestions. All that one could ask from them is to be, their coding, more documentation friendly, ensuring this way that their valuable and very respectable labor and creation won't go in vain.. As Viktor said, others will have to volunteer to do it, if the original developers don't feel like doing it. Or maybe they will do it once their work is relatively finalized? Then they won't have to change documentation so much when simple things change, and focus more on development. The ChangeLog keeps track of all this pretty nicely anyways. (Sorry Viktor... you had to tell me 2 or 3 times about making it a habit to check this file!) In other (good) news, I am working on compiling a very readable FAQ with pretty much everything covered that you could want in order to get something that compiled on Clipper to compile in Win32 for Harbour... as I had to figure it out all by myself, with the help of a few developers on the -dev list. So, this might help as far as teaching users how to do some basic and intermediate things with Harbour that are very common. ___ Harbour mailing list (attachment size limit: 40KB) Harbour@harbour-project.org http://lists.harbour-project.org/mailman/listinfo/harbour
