see below, please. regards,
Richard Erlacher ----- Original Message ----- From: <[EMAIL PROTECTED]> To: <sdcc-user@lists.sourceforge.net> Sent: Tuesday, September 02, 2008 1:31 PM Subject: Re: [Sdcc-user] documentation & open source generally > bobby wrote: > > They are separate issues, but there is a common thread running through > > both. For example, remembering that "SDCC is a free software", or "feel > > free to do better if you can", doesn't provide me with a lot of comfort. > > Statements such as these recognize, explain and/or excuse the existence > > of the problem, but do nothing to address it, but rather introduce the > > final exit, which usually looks something like this: "If you want better > > documentation, why don't you write it yourself", which of course is > > loaded with all kinds of contradictions. > > > > 1) It fails to address the problem. > > 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. > > > 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. > > > 3) They feign an interest in solving the problem, but inspire no one. > > you're completely overlooking one of the fundamental premises of > open source: people work on what it pleases them to work on. > This is the paradox of open-source software generation. People like to do the "fun" part, i.e. the coding and debugging, but most of them don't like the documentation, first because involving themselves in the documentation requires a discipline that the software industry rejected a couple of generations ago, abandoning engineering principles and adopting stream-of-consciousness as a template. I've long insisted that software generated under my supervision not be started, not even the first line of code, until the entire specification is complete and approved. This becomes difficult when observed from the standpoint of the independent open-source developer, as he has no externally imposed objective criteria on which to base his documentation. The result, of course, is that the end-product often differs considerably from what the developer would initially have specified, had he been required to do so. This doesn't mean that he ends up with a chess game when he intended to write an income-tax-preparation tool, but it does mean that asking the developer what, exactly, he's written can produce mixed results. > > if a developer is motivated by zillions of very happy newbie > users, then they'll probably work on docs as well as code. if > they don't care about anything except making a working program, perhaps > mainly for their own use, then they may just work on code. if > someone feels that making the program especially easy to _use_ is > important, they may just work on docs. these people all do what > they do because it scratches an itch. > An unlikely prospect if he's not written a pretty complete and detailed set of documentation along with correctly and properly commented code and accompanied it with design documentation. > > > 4) As a user, my input to the project (such as this offering and > > previous ones) is swept under the carpet as a 'gripe' or 'complaint'. > > your input, i'm sure, is noted. but actions speak much louder > than words. have you offered to help improve the docs? have you > created patches to modify or improve the help text? i suspect > such changes would be warmly received, and might even inspire a > developer to notice other areas that need improving. > One has to have a firm basis on which to make such recommendations and undertake such improvements. So long as this basis is absent, such results will be absent as well. > > > 5)et al, and etc. > > > > Am I mistaken or have I observed somewhere that opensource projects > > frequently have at least the semblance of an hierarchical management > > organization? > > some do. some don't. have you ever worked in an all-volunteer > organization? perhaps a local civic club, or similar unpaid group? > you can't _make_ anyone do something. and if someone _wants to do > something, it might not be quite what the "organizers" (whoever they > may be) want done. but often they'll be willing to let that person > go, because, after all, they're the one doing the work. > > an open source project is essentially a volunteer organization. > you can only influence its outcome by helping. criticism, or > constant sideline comments, almost never help. > I do believe it's volunteer, but there's room for doubt as to the organization part, else there'd be more discipline in the coding. In some works it's there, and in others it's not. However, there's more to writing durable and reliable code that will serve for many years, if there's rigidly imposed structure at the outset, enforced throughout the evolution of the project. 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 ?" > > paul > =--------------------- > paul fox, [EMAIL PROTECTED] > There is a GLOBAL problem with "missing pieces" throughout open-source materials. I refer, in this sense, more to open-source hardware than to software, as I've examined quite a bit of the hardware (open-source HDL) yet have spent little time on software, having examined at most 1E6 lines or so of it (mostly LINUX) in the past decade or so. I've seen lots of sloppily written, poorly documented code, mostly in the software realm, which, I guess, is why I've not become a LINUX user ... yet. I'm seriously interested in becoming knowledgeable about SDCC because, (a) it supports the architecture I've adopted as a favorite, and (b) it supports other architectures about which I'm knowledgeable and with which I have considerable experience. ------------------------------------------------------------------------- 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
