Richard, That's all very true.
That's also one of the things that holds open-source projects, software and hardware, back, and, often causes them to fall into relative disuse until someone not-so-open-source gloms onto them and reworks them into a commercial product. The commercialization of LINUX is one example. What's a common thread among all open-source projects is that the core precedes the documentation, hence, the documentation is difficult because the authors of the core product must, having worked long months and years of spare time, which they probably enjoyed to greater or lesser extent, certainly don't want to write documentation after the fact. It's very difficult to document your work after it's been "completed." That's why it's important to get the doc's done BEFORE the coding is started. When you're finished coding, then, you have something against which to test, not just "try out" your work to see how well you've done, what you've missed, etc. It's easy, too, to get wrapped up in an open-source project when you just jump in and start doing what you want, though it doesn't always lead where you intended to go. Now, I've offered to work up a User Guide, provided, of course, that I can find the information necessary in order to become a user. If that involves reading the code, then it had best be thoroughly documented code ... you see where this leads? I appreciate that the folks who are maintaining SDCC have their hands full dealing with problems and occasional "critters" that come up. I also know that those same people are not likely to find time to document SDCC, nor would they be likely to want to do that. I know that I'm presently unable to make use of SDCC. I also know that if I find out how to use it, I'd be in a much better position to produce useful documentation than if not. Is there anyone else who's better equipped with the energy and willingness to do this? I hope so. If I have to figure out how to use SDCC from poring over the code listings, I'll probably skip it and continue using assembly language. I'm comfortable with that. After all, sifting through the code is about a 10 k-hour investment, and that would be necessary to perform a < 1000-hour task. BTW, I'm not a Windows lover. I use it because it's just about impossible to buy a computer without it, aside from a MacIntosh, which I like even less. I'm a devoted user of DOS, at least for "useful work" since I can rely on that. With Windows, which is useful for compatibility with the rest of the world, and yes I know about the open-source tools that are "equivalent," all bets are off. I guess what I'm doing is complaining ... but I'm complaining that that's all I can do. regards, Richard Erlacher ----- Original Message ----- From: "Richard Gray" <[EMAIL PROTECTED]> To: <sdcc-user@lists.sourceforge.net> Sent: Thursday, August 28, 2008 3:13 PM Subject: [Sdcc-user] Poor documentation & open source generally > While I'm sympathetic to the cries of inadequate (or sometimes just plain > wrong) > documentation, I think this needs to be met with more understanding. > The Open Source development community is comprised of some rather clever > people that are prepared to sit and write useful software in their spare > time for > free and for nothing. People that write software are notoriously reluctant > to sit > and write documentation because, well, they just don't like doing it. > Unfortunately, this places some pressure upon would-be users to provide > some input of their own, which is to examine the source code for > themselves > and learn by experimentation - it's those same people that might later > decide > to contribute with documentation, worked examples "howto" guides and > so-on, > should they wish to join this very generous community themselves. > Unfortunately people have come to expect a professional finish (which it > does > get eventually) from people who are toiling away in their spare time, and > this > is a bit unrealistic. I don't admonish anyone to look at source code, > rather > exhort them to in the hope that they themselves might be able to > contribute > to the project one day. > Projects like SDCC are going to be niche projects with only a limited > number > of people able to contribute, and I've no doubt these people have day-jobs > too. > Bigger projects, like Open Office and Linux tend to be much better > documented > and better generally because of the comparatively large number of people > behind > them, and indeed through sponsorship - Linus Torvalds develops and > maintains > Linux for a living, for example. If enough money could be raked together > to > sponsor someone, or a group, to develop and maintain SDCC then we would > no-doubt see superb developments in a much shorter timescale; but this is > probably > an unlikely turn of events. > Then again, maybe if someone wants to try and persuade, say, Microchip Inc > that > it's in their interests to sponsor the development of the PIC forks of > SDCC, then > who knows? Even then, wrangling with companies over sponsorship is time > away > from the project coal-face, and many pro-grammers would find this tedious. > There > is a quite nice C compiler for PICs from some Australian outfit, I think, > (I cannot > remember the name) but this will cost you around £400 (GBP 400), and the > docu- > mentation is good and I found the simulator and cut-down teaser version > very good > when I last tried it; but I don't want to cough-up £400 or so for the > full-blown product > for projects that I write for free to help people out. For myself, I don't > want to be f > orced to use Windows, so SDCC is great if you're a Linux user, which I am, > exclusively. > When I've written some worthwhile stuff for the Z80/Z180 fork, I'll offer > it as > example code specifically to help others, and no-doubt I could make some > amendments to the manual too. > So, I'm suggesting that if you can do better then please feel free to do > so. Constructive > criticism and bug reports are great too. When you're an Open Source user > you're also > a developer, in however modest a way that might be. Complaining, well... > A last word for Windows users (apart from to try and wean yourselves off > it!), try > searching your file system for z180.h - once you have found this you will > have found > the general area of includes and libraries and such. /usr refers to a > Unix/Linux file > system and the Windows setup is probably different. -- Richard. PGP Key-id: 0x5AB3D350** > > > ------------------------------------------------------------------------- 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
