see below, please. regards,
Richard Erlacher ----- Original Message ----- From: "Jan Waclawek" <[EMAIL PROTECTED]> To: <sdcc-user@lists.sourceforge.net> Sent: Tuesday, September 02, 2008 4:12 PM Subject: Re: [Sdcc-user] documentation & open source generally > Richard, > >>> how? it suggests that someone who understands that there's a problem >>> should help solve that problem. >>> >>This is, in a sense, a circular argument. The one recognizing the >>problem, >>in this case, at least, is least prepared to do anything about it. > > Not quite. If he's willing to ask and understand/try/check/test/whatever > the offered answers, he might then very well be able to describe this > particular item. > Often one can ask, but receive nothing of any use in response. This notion can be applied to a code body of, perhaps, less than 100 lines, but not to something in the thousands of lines, particularly if it's written in the commonly cryptic uncommented 'C' by more than one person. What's to check? Against what benchmark can one test? What can be concluded from the result? > >>> > 2) Such requests typically come from _users_, not necessarily >>> > developers. >>> >>> who better than a user to help with documentation? after all, it's >>> users that know what questions need to be answered. >>> >>While inherently true and correct, this is misleading. Those who need the >>documentation the most are new, actually would-be, users, like me, who'd >>use >>a product if there were sufficient "instructional material" to make it >>readily useable. > > Most of the would-be users use SDCC and similar out of necessity - there's > no alternative given a certain budget (namely, $0). Only a few chose SDCC > because of other qualities of open-source software (e.g. possibility to > add a feature), but that's sort of a necessity as well. And, most of these > users, who WILL use SDCC anyway, need and will figure out this and that, > given the incomplete documentation. > I'd submit that there would be a lot more effort put into expansion and enhancement if one knew from the outset why a given piece of code was written in the way it was, what it intended to do, and, of course, why. Why use one data structure over another? The "why" is, ultimately, the key to understanding. > > It's just then up to their willingness to add these snippets they found > out, to some general pool of knowledge. This - incremental and > unorganized approach to documentation - is again something you don't > really like, but this might turn out to be the only way how to get to ANY > documentation. Take it or leave it. > Well, ask yourself ... "How many take it and how many leave it?" ... and why. > >>This doesn't mean >>that he ends up with a chess game when he intended to write an >>income-tax-preparation tool, > > Oh, but why not? Now, THIS would be REAL FUN indeed! :-) > Well, maybe, but as has been said a time or two, the developer most often begins a project out of necessity, usually because something either doesn't yet exist or costs entirely too much. If the chess game (and plenty of them already exist) will meet his need, then there's no real need to open-source-publish it, though I suppose he can if he wants to go on record as having reinvented the wheel ... Perhaps his wheel will be better ... > > >>SDCC's maintenance has been pretty consistent, but I'll bet there have >>been >>plenty of episodes of cursing, and of asking, "Why on earth did he do THIS >>?" > > Yeah; exactly as it happens so often in very well funded and thoroughly > organised projects. > Not so often ... Well-thought-out solutions don't normally wind up like that, and there's uncerlying documentation to explain it, even if it does. > > The problem (recognised and studied in deep detail by Mr Murphy) is, that > it's only after those years when you find out which parts of your work > were straightforward and crystal clear, and which were complex and > obscure - and, of course, it's exactly the opposite of what you thought > BACK THEN when the documentation was written... :-) > I've found few problems to be complex and obscure, though solutions tend to be, particularly when they're insufficiently studied and thought out, and therefore not well defined, before work begins. Often the problem lies in that a coder is unwilling to discard 20k lines because there's a much simpler solution, usually introduced by someone else, that requires only 400 lines written by someone else. I've seen it happen time and again, when a coder wants to re-use (and gain credit for) code from another project, often user-interface code, and it just doesn't fit the problem. > > Jan Waclawek > > ------------------------------------------------------------------------- ------------------------------------------------------------------------- This SF.Net email is sponsored by the Moblin Your Move Developer's challenge Build the coolest Linux based applications with Moblin SDK & win great prizes Grand prize is a trip for two to an Open Source event anywhere in the world http://moblin-contest.org/redirect.php?banner_id=100&url=/ _______________________________________________ Sdcc-user mailing list Sdcc-user@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/sdcc-user
