> [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 it would
be even more valuable if you told what exactly are
your concerns. Just to help things flowing.
Viktor
_______________________________________________
Harbour mailing list (attachment size limit: 40KB)
Harbour@harbour-project.org
http://lists.harbour-project.org/mailman/listinfo/harbour
